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A. Open Source Notice 


Preface 


Intended Audience 


This document is for application developers who want to use the Common Data Security Architecture (CDSA) 
to add security to their programs. 


This is not a tutorial manual. The reader should already have a basic understanding of fundamental 
cryptographic terms and principles, as well as a broad overview of CDSA services and architecture. 


Document Structure 

This manual consists of the following chapters: 

Chapter 1 contains a broad overview of CDSA. 

Chapter 2 provides important information about installation and initialization of CDSA. 
Chapter 3 describes administrative and development utilities provided with CDSA. 
Chapter 4 includes programming information and examples of using CDSA. 


Following the chapters is a reference section that describes the CDSA application programming interface 
functions (API functions), and a Glossary. 


Related Documents 
The following documents are recommended for further information: 


¢ HP Open Source Security for OpeVMS, Volume 2: HP SSL for OpenVMS. 
¢ DCL Help file for the API functions. (Enter the HELP CDSA command at the DCL prompt.) 


e« Release Notes for CDSA. For Version 7.3-1 and higher, the information is included in the Op¢VMS 
Rdease Notes. For Versions 7.2-2 and 7.3, the Release Notes for CDSA can be found in 
SYS$HELP:CDSA020.RELEASE NOTES. 


e [Intel CDSA documents, found in SYS$COMMON:[CDSA.DOCS]: 


— Inte Common Data Security Architecture Application Devdoper's Guide 
CDSA$APP_DEV_GUIDE.PDF 


— Intda Common Data Security Architecture Service Provide Devdoper's Guide 
CDSA$SP_DEV_GUIDE.PDF 


— Intd Common Data Security Architecture Manifest Signing Tools User's Guide: 
CDSA$MST_GUIDE.PDF 


¢ CDSA Technical Standard, available from The Open Group at the following Web site: 
http: //www.opengroup.org/onlinepubs/009609799 

e FIPS 186 Standard, available from the following Web site: 

http://www.itl.nist.gov/fipspubs/fip186-.htm 


For additional information about HP OpenVMS products and services, see the following World Wide Web 
address: 


http://www.hp.com/go/openvms 


For additional information about CDSA, visit the following Web sites: 


http://sourceforge.net/projects/cdsa 
http://www.intel.com/labs/archive/cdsa.htm 


Reader's Comments 


HP welcomes your comments on this manual. 


Please send comments to either of the following addresses:: 


Internet: openvmsdocGhp.com 


Postal Mail: 


Hewlett-Packard Company 
OSSG Documentation Group 


ZK O3-4/U 08 
110 Spit Brook Road 


Nashua, NH 03062-2698 


How to Order Additional Documentation 


For information about how to order additional documentation, visit the following World Wide Web address : 


http: //www.hp.com/go/openvms/doc/order 


Conventions 


The following conventions may be used in this manual: 


Convention Meaning 

Ctrl/x A sequence such as Ctrl/x indicates that you must hold down the key labeled 
Ctrl while you press another Key or a pointing device button. 

PF1x A sequence such as PF 1 x indicates that you must first press and release the 
key labeled PF 1 and then press and release another key (x) or a pointing 
device button. 

Return In examples, a key name in bold indicates that you press that key. 


A horizontal ellipsis in examples indicates one of the following possibilities: 
— Additional optional arguments in a statement have been omitted. 

— The preceding item or items can be repeated one or more times. 

— Additional parameters, values, or other information can be entered. 


A vertical ellipsis indicates the omission of items from a code example or 
command format; the items are omitted because they are not important to 
the topic being discussed. 


In command format descriptions, parentheses indicate that you must 
enclose choices in parentheses if you specify more than one. 


Convention 


Meaning 


[] 


{} 


bold type 


italic type 


UPPERCASE TYPE 


Example 


numbers 


In command format descriptions, brackets indicate optional choices. You can 
choose one or more items or no items. Do not type the brackets on the 
command line. However, you must include the brackets in the syntax for 
OpenVMS directory specifications and for a substring specification in an 
assignment statement. 


In command format descriptions, vertical bars separate choices within 
brackets or braces. Within brackets, the choices are optional; within braces, 
at least one choice is required. Do not type the vertical bars on the command 
line. 


In command format descriptions, braces indicate required choices; you must 
choose at least one of the items listed. Do not type the braces on the 
command line. 


Bold type represents the introduction of anew term. It also represents the 
name of an argument, an attribute, or a reason. 


Italic type indicates important information, complete titles of manuals, or 
variables. Variables include information that varies in system output 
(Internal error number), in command lines (/PRODUCER=name), and in 
command parameters in text (where (dd) represents the predefined par code 
for the device type). 


Uppercase type indicates a command, the name of a routine, the name of a 
file, or the abbreviation for a system privilege. 


This typeface indicates code examples, command examples, and interactive 
screen displays. In text, this type also identifies URLs, UNIX command and 
pathnames, PC-based commands and folders, and certain elements of the C 
programming language. 


A hyphen at the end of a command format description, command line, or 
code line indicates that the command or statement continues on the 
following line. 


All numbers in text are assumed to be decimal unless otherwise noted. 
Nondecimal radixes — binary, octal, or hexadecimal — are explicitly 
indicated. 


Introduction to CDSA 
What Is CDSA? 


1 Introduction to CDSA 


This chapter provides an overview of key components of the Common Data Security Architecture (CDSA) and 
its set of integrity services. 


What Is CDSA? 


The Common Data Security Architecture (CDSA) is a multiplatform, industry-standard security 
infrastructure. Starting with Version 7.3-1, HP provides CDSA as part of the OpenVMS Alpha operating 
system. CDSA is compatible with OpenVMS Alpha Version 7.2-2 and higher. 


CDSA provides a stable, standards-based programming interface that enables applications to access 
operating system security services. With CDSA, you can create cross-platform, security-enabled applications. 
Security services, such as cryptography and other public key operations, are available through a dynamically 
extensible interface to a set of add-in modules. These modules can be supplemented or changed as business 
needs and technologies evolve. 


CDSA is security middleware that provides flexible mix-and-match solutions across a variety of applications 
and security services. CDSA insulates you from the issues of incorporating security into applications, freeing 
you to focus on the applications themselves. The security underpinnings are transparent to the user. 


CDSA was originally developed by Intel® Architecture Labs and was released to the OpenSource community 
in May 2000. HP's CDSA implementation is based on the Intel V2.0 Release 3 reference platform, which 
implements CDSA V2.0 with Corrigenda, as defined in The Open Group's Technical Standard C914, May 
2000. 


CDSA Overview 


The CDSA layered architecture is shown in Figure 1-1 on page 10. 
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Figure 1-1 CDSA Layered Architecture 
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Applications call the Common Security Services Manager (CSSM), which implements the CDSA APIs. The 
CSSM alsoimplements the CDSA integrity services and security contexts. The managers for each of the 
CDSA add-ins are also part of CSSM. CSSM is described in more detail in “Common Security Services 
Manager (CSSM )” on page 11. 


In addition to the CSSM, CDSA includes the following: 

e« Service provider modules - See “Service Provider Modules” on page 11 

e Elective module Managers (EM Ms) - See “Elective Module Managers (EMMs)” on page 16 
e Module directory Services (MDS) - See “Module Directory Services (MDS)” on page 16 


Chapter 4, “CDSA Programming Concepts,” on page 35 provides sample C programs that illustrate the use of 
CDSA. 


For additional information about CDSA, see the web links listed in the Preface. 


10 Chapter 1 


Introduction to CDSA 
CDSA Overview 


Common Security Services Manager (CSSM) 


The Common Security Services Manager (CSSM) is the heart of CDSA. It is a shared library (in 
SYS$SHARE :CDSA$INCSSM 300_SHR.EXE) to which applications can link to obtain security services. It 
defines both the API and the service provider interface (SPI) for add-in security service modules. CSSM 
includes a set of core services that are common to all categories of security services. These services perform 
functions such as: 


¢ Dynamic attach of an add-in security module 

e Enforced integrity, authentication, and exemption verification when dynamically attaching services 
e Secure linkage checks on calls to service provider modules 

¢« General integrity services 


Applications call functions in the CSSM API, which is fully specified by the CDSA Technical Standard 
(located at http:/Awww.opengr oup.org/onlinepubs/009609799/). API function names are prefaced with CSSM _ 
and are sometimes followed by the designation of the module that will actually handle the request. For 
instance, applications call CSSM_DL_DbOpen () to direct a DL module to open a data store. The associated SPI 
for this module is DL_DbOpen (). (The SPI interface is not directly callable by CDSA applications.) 


An application begins by initializing its connection to CSSM using the cSsM_Init () routine. The application 
can use Module Directory Services (MDS) to inquire about available modules and their supported 
functionality (seean MDS examplein “MDS Example Program” on page 44) or it can directly access a specific 
service provider by using its global unique identifier (GUID). The application loads the desired module using 
the CSSM_ModuleLoad() routine and then attaches to it using the CSSM_ModuleAttach () routine. 


The CSSM is implemented as a sharable image on OpenVMS. Header files (in 
CDSA_SYSDIR:[INCLUDES]*.H) define the CSSM API. 


Service Provider Modules 

There are several types of add-ins for CDSA, each supporting a different security task: 

¢ Cryptographic Service Provider (CSP) modules (see “Cryptographic Service Providers (CSPs)” on page 11) 
¢ Trust Policy (TP) modules (see “Trust Policy (TP) Modules” on page 15) 

e Authorization Computation (AC) modules (see “Authorization Computation (AC) Modules” on page 15) 

¢« Certificate Library (CL) modules (see “Certificate Library (CL) Modules” on page 15) 

¢« Data Storage Library (DL) modules (see “Data Storage Library (DL) Modules” on page 15) 


On OpenVMS, service providers are implemented as sharable images. 


Cryptographic Service Providers (CSPs) 


The Cryptographic Service Providers (CSPs) are add-in modules to the Common Security Services M anager 
(CSSM). CSPs perform cryptographic operations and securely store cryptographic keys for the applications 
that call them through the CSSM API. A CSP can bein the form of software, hardware, or both. 


Applications call these CSPs to provide authentication, data integrity, data and communication privacy, and 
nonrepudiation of messages to users. 


CSPs implement the following cryptographic algorithms, among others, in one or more modes: 
¢ Bulk encryption algorithm in modes DES, Triple DES, DESX, RC2, RC4, and RC5 
¢ Digital signature algorithm in modes RSA and DSS 
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¢ Key negotiation algorithm in modes Diffie Hellman and DSA 
¢ Cryptographic hash algorithm in modes MD4, MD5, and SHA1 


CSPs also provide the following services: 


e« Unique identification number: hard coded or random generated 
¢ Random number generator: attended and unattended 

e Encrypted data: symmetric keys and private keys 

e Secure key storage 

e« Custom facilities unique to the CSP 


The CSP module manager administers the CSPs that are installed on the local system. It defines a common 
API to access all of the Cryptographic Service Providers that can be attached and used by any caller in the 
system. 


The specific security services API functions that are defined by the CSP module manager include the 
following service categories: 


SignData 
VerifyData 
DigestData 
EncryptData 
DecryptData 
GenerateK eyPair 
GenerateR andom 
WrapKey 
UnwrapK ey 


CDSA on OpenVMS provides CSPs based on OpenSSL and RSA BSAFE: 
¢ OpenSSL CSP 
— Message authentication based on MD5 and SHA1 
— Symmetric encryption based on DES 
e RSA BSAFE CSP 
— Message authentication based on MD5 and SHA1 
— Symmetric encryption based on DES, triple DES, DESX, and RC2, RC4, and RC5. 
— Asymmetric encryption based on RSA, DSA, and Diffie-Hellman 
The following sections discuss these topics: 
e Establishing a session to usea CSP (see “Establishing a Session” on page 12) 
¢ Defining the security context (see “Defining a Security Context” on page 13) 
e Using keys (see “Using Keys” on page 13) 
Establishing a Session An application establishes a session to select a particular CSP. Once attached, the 


application can initiate a cryptographic login session with the CSP. The application requests additional 
credentials, such as a passphrase or PIN, to gain access to specific keys and services managed by the CSP. 


Within a module attach session or a cryptographic login session, an application creates, uses, and discards 
cryptographic contexts. A cryptographic context carries the parameters required to perform a cryptographic 
service. The cryptographic context can be used for the following: 
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« A one-step cryptographic operation in which only one call is needed to obtain the result. 


e« Accryptographic session of a multistaged cryptographic service, in which an initialization call is followed 
by one or more update calls, ending with a completion (final) call. For most cryptographic operations, the 
result is available after the final function completes its execution. An exception is staged 
encryption/decryption, in which each update call generates a portion of the result. 


Depending on the class of cryptographic operations, individualized attributes are available for the 
cryptographic context. In addition to specifying an algorithm when creating the context, the application can 
also initialize a session key, pass an initialization vector, or pass padding information to complete the 
description of the session. A successful return value from the create function indicates that the desired CSP is 
available. 


Functions are also provided to manage the created context. The cryptographic context contains most or all of 
the input parameters required for an operation. Some cryptographic service functions accept input 
parameters in addition to the CSP handle and the context handle. These input parameters always take 
precedence over any duplicate or conflicting parameters in the cryptographic context. When a context is no 
longer required, the application calls a DeleteContext function. Resources allocated for that context can then 
be reclaimed by the operating system. 


Defining a Security Context The application's associated security context defines parameter values for 
the low-level variables that control the details of cryptographic operations. For example, an application 
issuing a request to the EncryptData call can reference a security context that defines the following 
parameters: 


¢« Thealgorithm to be used (such as DES) 

e« Algorithm-specific parameters (Such as key length) 

¢ The object on which the operation is conducted (such as a set of buffers) 
e Thecryptographic variables (such as the key) 


Most applications use predefined, default contexts. Typically, a distinct context is used for encrypting, 
hashing, and signing. For an initialized application, these contexts change little, if at all, during the 
application's execution or between executions. This allows the application developer to implement security by 
manipulating certificates, using previously defined security contexts, and maintaining a high-level view of 
security operations. 


Using Keys In CDSA, there are two main types of cryptographic algorithms that use keys: 


¢ Asymmetric algorithms use one key to encrypt and a second key to decrypt. They are often called 
public-key algorithms. One key is called the public key and the other is called the private key or secret 
key. RSA (Rivest-Shamir-Adelman) is the most commonly used public-key algorithm. It can be used for 
encryption and for signing. 


¢ Symmetric algorithms use a single secret key for encryption and decryption. Both the sender and 
recei ver must know the secret key. Well-known symmetric functions include DES (Data Encryption 
Standard) and IDEA. DES was endorsed by the U.S. Government as a standard in 1977. It's an encryption 
block cipher that operates on 64-bit blocks with a 56-bit key. It is designed to be implemented in 
hardware, and works well for bulk encryption. |DEA (International Data Encryption Algorithm) uses a 
128-bit key. 


Every CSP implements its own secure, persistent storage and management of private keys. To support chains 
of trust across application domains, CSPs support importing and exporting of public and private keys among 
remote and possibly foreign systems. To transfer keys, the CSP must be able to convert one key format into 
any other key format and to secure the transfer of private and symmetric keys. 
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Each CSP is responsible for securely storing the private keys it generates or imports from other sources. 
Additional storage-related operations include retrieving a private key when given its corresponding public 
key and wrapping private keys as key blobs for secure exportation to other systems. 


On an OpenVMS Alpha system, the CSP stores private key files in EAYCSP.PRI and MAF_BSAFE.PRI. The 
protections on the key files are OWNER:READ,WRITE,DELETE. The key files are user-specific and are 
stored in the [.CDSA.PKD] subdirectory in the user's login directory. 


Public Key Infrastructure (PKI) 


The Public Key Infrastructure (PKI) is the state-of-the-art method, ultimately to be applied worldwide, for 
secure and confidential electronic transactions. It employs public and private keys. 


Thetwo PKI algorithms in widespread use are: 


e RSA-based algorithms 
« DSA-based algorithms 


For RSA-based algorithms, CDSA uses the PK CS #1 standard for key representation. For DSA-based 
algorithms, no organization has published a standard. CDSA's representation of the DSA key is based on the 
DSA algorithm definitions in the FIPS 186 standard. (See the Preface for web links to this and other 
standards.) 


A DSA public key is represented as a BER-encoding of a sequence list that contains the following: 
PrimeModulus; /* p */ 

PrimeDivisor; /* q */ 

OrderQ; /* g */ 

Publickey; /* y */ 

A DSA private key is represented as a BER-encoded sequence list that contains the following: 
PrimeModulus; /* p */ 

PrimeDivisor; /* q */ 

OrderQ; /* g */ 

PrivateKey; /* x */ 

These key components are defined as follows by FIPS 186 and FIPS 186a: 

e« PrimeModulus. This is the public prime modulus. 


p =A prime modulus, where 2/1 <p <2! for 512 <=L <=1024, and LL is a multiple of 64. 
¢ PrimeDivisor. Another public prime number dividing (p-1). 

q =A prime divisor of p-1, where 29 <q <2160 
¢ OrderQ. This public number has order q mod p. 

g =h "P29 mod p, where h is any integer with 1 <h <p-1, such that h '°)) /q mod p >1. 
¢  PrivateK ey. The private key. 

X =a pseudorandomly generated integer with 0 <x <q. 
¢ Publick ey. The public key. 

y =g* mod p. 


A DSA-wrapped private key is defined by the PKCS#8 specification. The PK CS#8 standard specifies the 
wrapped key format resulting from encoding an algorithm object identifier (O1D) with an encoded private key. 
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Trust Policy (TP) Modules 


Trust Policy modules allow applications to request security services that require "policy review and approval" 
as the first step in performing the operation. Approval can be based on the identity, integrity, and 
authorization represented in a group of digital certificates. 


Trust Policy modules implement policies defined by authorities and institutions. Policies define the level of 
trust required before certain actions can be performed. Three basic action categories exist for all 
certificate-based trust domains: 


e Actions on certificates 

e Actions on certificate revocation lists 

« Domain-specific actions (such as issuing a check or writing a file) 

The Trust Policy function can invoke certificate and data storage library functions to carry out the mechanics 
of the approved action. 

Authorization Computation (AC) Modules 


Authorization Computation modules define a general authorization evaluation service that computes 
whether a set of credentials and samples are authorized to perform a specific operation on a specific object. 
AC modules implement an authorization evaluation mechanism based on caller inputs. Callers provide: 


« Theassumptions forming the basis of the caller's policy 
e Therequest for which authorization is being checked 
¢ Thecredentials, samples, and exhibits that could demonstrate authorization to perform the request 


The Authorization Computation engine determines whether the request is authorized based on the 
assumptions and caller credentials. The AC module can provide other services related to authorization 
computations through the cCSSM_AC_PassThrough () function. 


Certificate Library (CL) Modules 


The Certificate Library API allows applications to manipulate memory-resident certificates and certificate 
revocation lists. Operations must include creating, signing, verifying, and extracting field values from 
certificates. Each add-in certificate library incorporates knowledge of certificate data formats, and how to 
manipulate that format. 


TheCSSM Certificate API defines the generic operations that should be supported by every CL module. Each 
module can choose to implement only those operations required to manipulate a specific certificate data 
format, such as X.509, SDSI, etc. 


The implementation of these operations is intended to be semantic-free. Semantic interpretation of 
certificate values is designed to be implemented in Trust Policy modules, layered services, and applications. 


The Certificate Library module provided on OpenVMS systems can manipulate X509V3 certificates and SPK| 
(Simple Public Key Infrastructure) certificates. 
Data Storage Library (DL) Modules 


The Data Storage Library allows applications to search and select stored data objects, and to query 
meta-information about each data store (such as its name, date of last modification, size of the data store, and 
so on). 


Data Storage Library modules provide stable storage for security-related data objects. These objects can be 
certificates, certificate revocation lists, cryptographic keys, integrity and authentication credentials, policy 
objects, or application-specific objects. Stable storage can be provided by one of the following: 
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« Commercially-available database management system product 
« Native filesystem 

e« Custom hardware-based storage device 

e« Remote directory services (e.g., LDAP) 

e« |In-memory storage 


Each Data Storage Library module can choose to implement only those operations required to provide 
persistence under its selected model of service. 


The Data Storage Library module currently provided on OpenVMS uses OpenVMS flat files. 


Elective Module Managers (EMMs) 


The CDSA architecture includes several extensibility mechanisms. Elective module managers support the 
dynamic addition of entire new categories of service. Prior to requesting services from an add-in service 
provider module, the application attaches to an instance of the service provider. For elective module 
managers, the CSSM transparently attaches the associated module manager if it is not already loaded. Once 
the manager is loaded, the APIs defined by that module are available to the application. 


This process is transparent to the add-in module as well as to the application. Therefore, an add-in module 
vendor should not need to modify their module implementation to work with an elective module manager 
versus a basic module manager. 


Module Directory Services (MDS) 


The Module Directory Services provide facilities to describe and locate executable objects and their associated 
signed manifest integrity credentials. 


MDS consists of a database and a set of access methods. It is used primarily to support secure loading and the 
use of add-in software modules. It is a system-wide service available to all processes. MDS defines a basic 
object directory schema to name and locate software components and the signed manifest credentials 
associated with those software components. Each software component in the object directory is uniquely 
named by a globally unique identifier (GUID). CDSA defines an additional set of schemas to store 
CDSA-specific security attributes of all CDSA components. CDSA components use the MDS-managed data to 
do the following: 


e Discover other available CDSA components 

e Learn about the capabilities and properties of other CDSA components 

e« Locate the executables for CDSA components 

e Locate the signed manifest credentials associated with a CDSA software component 


New schemas can be defined to store the properties and capabilities of elective CDSA modules as they are 
defined. CDSA applications can also define MDS schemas and use MDS services. CDSA components use 
MDS managed data to support CDSA's software authentication and integrity checking procedure, known as 
bilateral authentication. 


Chapter 4, “CDSA Programming Concepts,” on page 35 provides an example of how to use MDS. 
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Maintaining CDSA Integrity 


As the foundation of the security framework, CSSM provides a set of integrity services that can be used by 
CSSM, module managers, add-in modules, and applications to verify their own integrity, and the integrity, 
identity, and authorizations of other components in the CDSA environment. 


CSSM's set of self-contained security services establishes a security perimeter around CDSA. These services 
incorporate techniques to protect against malicious attacks. Because application and add-in security service 
modules are dynamic components in the system, CSSM uses and requires the use of a strong verification 
mechanism to screen all components as they are added to the CSSM environment. 


Applications can extend CSSM's security perimeter to include themselves by using bilateral authentication, 
integrity verification, and authorization checks during dynamic binding. 


The establishment of integrity between two dynamically loaded, executable objects proceeds in three phases: 
e  Self-check 
e Bilateral authentication 


e Secure linkage check 


Self-Check 


In the first phase, the self-check phase, the software module checks its own digital signature. The Embedded 
Integrity Services Library (EISL) defines a statically linked library procedure to perform self-check. 


Bilateral Authentication 


In the second phase, bilateral authentication routines in the EISL offer support for securely loading, 
verifying, and linking to partner software modules. The process of bilateral authentication begins in the MDS 
registry, where each program can find the credentials as well as the object code of all other CDSA modules. 


Verification of other modules can be done prior to loading, or, if a module is already loaded, it can be verified 
in memory. Verification prior to loading prevents activating file viruses in infected modules. Verification in 
memory prevents stealth viral attacks where the file is healthy, but the loaded code is infected. 


Secure Linkage Check 


Once verified, programs can use the verified in-memory representation of the credentials to perform validity 
checks of addresses to provide secure linkage to modules. The addresses of both the callers and the 
procedures to be called can be verified using the Secure Linkage Check facility. 
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2 Installation and Initialization 


This chapter provides important information about CDSA installation and initialization. 


NOTE 


You must have the SYSPRV and CMKRNL privileges to initialize CDSA. Users of CDSA 


applications do not need SY SPRV, but you will likely need SYSPRV to develop CDSA signed 
applications and plugins 


Table 2-1 lists the currently supported versions of CDSA, and the installation and configuration requirements 
for the versions of OpenVMS that support CDSA. 


Table 2-1 CDSA Installation and Configuration Summary 
OpenVMS - : 
Vercion CDSA Version 1.0 CDSA Version 2.0 
V7.2-2&V7.3 1. Install CDSA kit. 1. Install CDSA kit. 
hose Pade 27) 2. Execute this command: 2. Execute this command: 
@BY S$STARTUP:CDSAS$INITIALIZE @BY S$STARTUP:CDSA$U PGRADE 
V7.3-1 (See 1. CDSA is already installed. 1. Install CDSA kit. 
page20) 2. Execute this command: 2. Execute this command: 
@BY S$STARTUP:CDSASINITIALIZE @BY S$STARTUP:CDSA$U PGRADE 
V7.3-2 (See V1.0 is not supported 1. CDSA is already installed. 
page 19) 


2. Execute this command: 
@SYS$STARTUP:CDSA$U PGRADE 


Installation of CDSA on OpenVMS Alpha Version 7.3-2 


If you install or upgrade to OpenVMS Alpha Version 7.3-2, CDSA Version 2.0 is automatically installed. 
Before you can use CDSA Version 2.0, however, you must execute the following command to initialize CDSA: 


$ @SYSSSTARTUP : CDSASUPGRADE 


Note that you must have the SYSPRV and CMKRNL privileges to execute this procedure. This command 
automatically calls CDSASINITIALIZE(). 
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Installation of CDSA on OpenVMS Alpha Version 7.3-1 


CDSA Version 1.0 is automatically installed when you install OpenVMS Alpha Version 7.3-1. However, you 
can install and run CDSA Version 2.0. The following sections provide important setup and initialization 
information for whichever version of CDSA you use. 


CDSA Version 2.0 Setup and Initialization 


If you want to run CDSA Version 2.0 on OpenVMS Version 7.3-1, you must manually install the CDSA 
Version 2.0 kit, which is included on the OpenVMS Version 7.3-2 media. Use the following command to install 
CDSA Version 2.0 on a Version 7.3-1 system: 


$ PRODUCT INSTALL CDSA /SOURCE=disk: [directory] 


Before you can use CDSA Version 2.0, you must perform the following manual procedure, for which you must 
have SYSPRV privileges. Execute the following command to initialize CDSA Version 2.0: 


$ @SYSSSTARTUP : CDSASUPGRADE 


This procedure automatically runs CDSA$INITIALIZE. It is not necessary to rerun any initialization 
procedure when the system is rebooted; therefore, you do not need to add the initialization to the OpenVMS 
startup procedures. 


The CDSA$UPGRADE procedure can take a few minutes, depending on your processor and disk speeds. 
When the procedure is run interactively, you will see system messages similar to the following: 


S$ @SYSS$STARTUP : CDSASUPGRADE 
Module uninstalled successfully. 
Module uninstalled successfully. 
Module uninstalled successfully. 


CDSA has previously been initialized on this system. 
Re-initializing CDSA. 


Installing CDSA 


**x* Installing MDS 
MDS installed successfully 


*** Installing CSSM 


Module installed successfully 
*** Installing FFDL 


Module installed successfully. 
*** Installing 509CL 


CDSA Initialization complete 
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CDSA Version 1.0 Setup and Initialization 


Although CDSA Version 1.0 is automatically installed as part of OpenVMS Alpha Version 7.3-1, setup and 
initialization of CDSA are not. Before you can use CDSA Version 1.0, you must perform the following manual 
procedure, for which you must have SY SPRV privilege. Enter the following command to initialize CDSA 
Version 1.0: 


$ @SYSSSTARTUP:CDSASINITIALIZE 


During initialization, CDSA checks to see whether the CDSA_SYSDIR:[CDSAF FDB] and 
CDSA_SYSDIR:[REGISTRY...] directories are both present. If one is missing, CDSA outputs the following 
message: 


The existing CDSA configuration on this system is corrupt. 


If this occurs, you can recover by deleting both directories and rerunning the CDSA initialization procedure. 
However, you will lose any CDSA information that has already been stored. 


It is not necessary to rerun the initialization procedure when the system is rebooted; therefore, you do not 
need to add the initialization to the OpenVMS startup procedures. 


The CDSA$INITIALIZE procedure can take 5 minutes or longer, depending on your processor and disk 
speeds. When the procedure is run interactively, you will see system messages similar to the following: 


$ @SYSSSTARTUP:CDSASINITIALIZE 


Installing CDSA 

*** Installing MDS 

MDS installed successfully. 
*** Tnstalling CSSM 


Module installed successfully. 


*** Installing FFDL 
Module installed successfully. 


*** Installing 509CL 


CDSA Initialization complete 


When a new version of CDSA is installed (for example, in an upgrade from a field test version to a production 
version, or an upgrade to a new version of OpenVMS), the CDSA upgrade procedure must be run. (See “CDSA 
Version 2.0 Setup and Initialization” on page 20.) Any CDSA application should be shut down before you run 
the initialization or upgrade procedure. 


Warning Against Uninstalling CDSA from OpenVMS Alpha Version 7.3-1 or 
Higher 


The POLY CENTER Software Installation utility command PRODUCT REMOVE is not supported for CDSA 
on OpenVMS Alpha Version 7.3-1 or higher, even though there is an apparent option to remove CDSA. (This 
option is due to the use of the POLY CENTER Software Installation utility in the installation.) CDSA is 
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installed together with the operating system and is tightly bound with it. An attempt to remove it from 
Version 7.3-1 or higher would not work cleanly and could create other undesirable side effects. An attempt to 
remove CDSA results in the following message: 


SPCSI-E-HRDREF, product CPQ AXPVMS CDSA Vx.x is 
referenced by DEC AXPVMS OPENVMS V7.3-2 
-PCSI-E-HRDRF1, the two products are tightly bound 
by this software dependency 


Installation of CDSA on OpenVMS Alpha Version 7.3 or 7.2-2 


On OpenVMS Alpha Version 7.3 or 7.2-2, CDSA is not included in the operating system installation. However, 
CDSA is compatible with these versions and can be installed separately. 


Use the command PRODUCT INSTALL toinstall CDSA. The following is a log of a CDSA installation: 


$ PRODUCT INSTALL CDSA /SOURCE=disk: [directory] 


The following product has been selected: 
CPQ AXPVMS CDSA V2.0 Layered Product 


Do you want to continue? [YES] 
Configuration phase starting 


You will be asked to choose options, if any, for each selected product and for 
any products that may be installed to satisfy software dependency requirements. 


CPQ AXPVMS CDSA V2.0 


Do you want the defaults for all options? [YES] 


Do you want to review the options? [NO] 


Execution phase starting ... 


The following product will be installed to destination: 
CPQ AXPVMS CDSA V2.0 DISKSSYSTEM: [VMSSCOMMON. ] 


Portion done: 
0%...10%...20%...30%...40%...50%...60%...70%...80%...90%...100% 


The following product has been installed: 
CPQ AXPVMS CDSA V2.0 Layered Product 


CPQ AXPVMS CDSA V2.0 


After Installation on OpenVMS Alpha Version 7.3 or 7.2-2 
CDSA requires post-installation work on OpenVMS V7.2-2 and V7.3. 


To complete the installation of CDSA, add the following line to the system startup file: 


$ @SYSSSTARTUP: CDSASINSTALL_IMAGES .COM 
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In addition, you need to add the following logical name definition to SY SS$MANAGER:SYLOGICALS.COM: 
$ cdsa_sysdir = f$trnlnm("SYS$COMMON") - "]" + "CDSA.]" 


S Define/system/exec/trans=conc cdsa_sysdir 'cdsa_sysdir 


Prior to the first time that CDSA is used, CDSA must be initialized, on a one-time basis. To accomplish this 
for CDSA V1.0, execute the following command file as shown: 


S@SYSSSTARTUP:CDSASINITITIALIZE 


To accomplish this for CDSA V2.0, execute the following command file as shown: 


$ @SYSSSTARTUP : CDSASUPGRADE 


There is no need to add either of these initialization files to any of the system startup files, as the 
initialization does not need to be rerun after a system restart. 


If you want to remove CDSA from your OpenVMS Alpha Version 7.3 or 7.2-2 system, you can do so with the 
POLY CENTER Software Installation utility command PRODUCT REMOVE. (This command cannot be used 
to remove CDSA from a Version 7.3-1 or higher system, as described in “Warning Against Uninstalling CDSA 
from OpenVMS Alpha Version 7.3-1 or Higher” on page 21.) 


Post-I nstallation Tasks 


Once you have installed CDSA, you should perform the tasks described in the following sections. 


Defining CDSA Symbols 


To define symbols for CDSA developers, add the following command to the SY S$MANAGER:SYLOGIN.COM 
file on the system where CDSA development work is being done: 


$ @SYSSMANAGER: CDSASSYMBOLS.COM 


NOTE The file SYS$MANAGER:CDSA$SYMBOLS.COM does not exist for CDSA Version 1.0, soit is 
not present on an OpenVMS Version 7.3-1 system unless a CDSA Version 2.0 kit has 
subsequently been installed. 


If this command is not defined at the system level in SY_LOGIN.COM, individual CDSA developers should 
add it to their personal LOGIN.COM file so that they can use the symbols. 


Backing up the CDSA Database 


HP recommends that you back up the CDSA database and registry files on a regular basis and when any 
major changes to the data are planned. For example: 


S$ BACKUP CDSA_SYSDIR: [CDSAFFDB]*.* - 

_S disk: [directory...]CDSA_DB_BACKUP .BCK/SAV 

S$ BACKUP CDSA_SYSDIR: [REGISTRY...]*.* - 

_$ disk: [directory...]CDSA_REGISTRY_BACKUP.BCK/SAV 


Chapter 2 23 


Installation and Initialization 
Post-Installation Tasks 


24 Chapter 2 


CDSA Utility Programs 
CDSA$CERTGEN.EXE 


3 CDSA Utility Programs 


This chapter describes a number of administrative and development utilities that are provided with CDSA. 
Note that some of these programs are typically called only from the CDSA initialization command file unless 
new add-in modules are being provided. 


The CDSA utility programs comprise the following: 

« CDSA$CERTGEN.EXE - Generates digital certificates. 

« CDSA$ISSUER.EXE - Generates the issuer key functions. 

« CDSA$MDS _INSTALL.EXE - Creates the MDS database. 

« CDSA$MOD_INSTALL.EXE - Adds entries to the MDS database. 

« CDSA$OUTPUT_ERROR.EXE - Translates numeric CDSA error codes into text. 
¢ CDSA$SIGN.EXE - Creates manifests. 

« CDSA$X5092XML.EXE - Extracts the subject name from an X509 certificate. 


The shortened program names listed in this chapter's Synopsis sections are defined in the file 
SYS$MANAGE R:CDSA$SY MBOLS.COM. The following command should be added to the 
SYS$MANAGE R:SYLOGIN.COM file on the system where CDSA development work is being done: 


$ @SYSSMANAGER: CDSASSYMBOLS.COM 


If this command is not defined at the system level, individual CDSA developers should add it to their personal 
LOGIN.COM file so that they can use the shortened program names. 


CDSA$CERTGEN.E XE 


Thecertgen utility allows the user to create digital certificates in the form runfilename.cer. Private keys will 
be placed in [.CDSA.PKD]csp-name.PRI under the login directory of the current process. 


This program generally is called by CDSA_SYSDIR:[SIGN]JCDSA$GEN_CERTS.COM. 


SYNOPSIS 


certgen [runfilename] 


OPTIONS 


runfilename This optional parameter specifies the name of the run file that contains the parameters that 
certgen needs to create a certificate. If norun file is specified, the default run file is 
certgen.run in the current directory. 


A certgen run file contains the following items as appropriate, each on a separate line: 
certype location 


certtype can be one of the following: 
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-s Indicates a self-signed certificate. 
-i Indicates a certificate signed by another certificate. 
-v Indicates that the created certificate takes its subject and public key from 
a certificate issued by another vendor. You cannot use this option to create 
a self-signed certificate. 
location Indicates where the issuer certificate is read from if -i or -v is specified. 
filename 


If certtype iS -s Or -i, filename indicates the location of the XML template that contains 
the Subject Name that must go into this certificate. If certtype is -v, filename indicates 
the location of the Vendor Certificate. 


algorithm 


Indicates the algorithm used to generate the key pair associated with the certificate being 
created. The specified algorithm must be supported by one of the Cryptographic Service 
Providers available in the local implementation of CDSA. The algorithm can be either DSA 
or RSA. This parameter is not valid if -v is specified for certtype. 


keysize 


Specifies the logical key size (in bits) of the key pair being generated. Typical examples are 
128, 256, 512, 1024, and soon. The specified key size must be supported by one of the 
Cryptographic Service Providers available in the local implementation of CDSA. This 
parameter is not valid if -v is specified for certtype. 


cspguid 

The globally unique identifier of the Cryptographic Service Provider that is being used. 
certfile 

The output file into which the created certificate is to be written. 
subject_password 


The password used to protect a key pair if one is being generated. This parameter is not 
valid if -v is specified for certtype. 


issuer_password 


The password used to unlock the private key required to sign the generated certificate. This 
parameter is not valid if -s is specified for certtype. 


validity_period 


The validity period for the certificate. This parameter contains a start and end date for the 
validity period in the form YYMMDDHHMMSS YYMMDDHHMMSS. The validity period 
cannot extend beyond the year 2049. If validity_period is not specified, the validity 
period for the certificate lasts for exactly one year. 


EXAMPLE 


$ certgen intmods.run 


The following is an example of a run file (intmods. run) that creates a certificate named intmods.cer, which 
is signed by intmanf.cer and generates a 1024-bit DSA key pair. 
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{67ef50d0-fe74-11d2-a8e6—-0090271d266f } 


intmods.cer 
intmods 
intmanf 


001013000000 101013000000 


CDSAS$ISSUER.E XE 


Theissuer utility is used to create a set of functions that are embedded into CSSM, or are used by EISL.A 
CDSA application developer needs to create only the EISL_RetrieveSelfCheckKey () function. The other 
functions noted here are applicable only for CDSA vendors (in this case, HP). 


This program generally is called by CDSA_SYSDIR: [SIGN] CDSASGEN_CERTS .COM(). 


SYNOPSIS 


issuer option certfile codefile functionname 


OPTIONS 


option 


certfile 


codefile 


functionname 
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A code that defines the function to be created. Specify one of the following values: 


-i Creates a function that returns an issuer name from the certificate. 
-s Creates a function that returns a signer name from the certificate. 
-k Creates a function that returns a trusted public key. 


Note: A CDSA application developer who is creating the EISL_RetrieveSel fCheckKey () 
function should specify -k. The other codes are used only by CDSA vendors who are 
building CDSA itself rather than a CDSA application or service provider module. 


A text file that contains the name of the certificate to be used. 


The file to which the generated function is written. 


Name of the function to be generated. 


Note: CDSA application developers need to create only the 

EISL_RetrieveSelfCheckKey () function (the last item in the following list). The full set of 
functions is listed here to provide a complete overview of the issuer utility. The other 
functions are applicable only for CDSA vendors. Those who want to learn more about export 
chains can refer to the _Intd Common Data Security Architecture M anifest Signing Tools 
User's Guide 
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* cssm_GetIntegrityRootKeys() (or cssm_GetExportRootKeys () for export) 


* cssm_GetIntegrityRootNames () (Of cssm_GetExportRootNames () for export) 


° EISL_RetrieveSelfCheckKey () 


EXAMPLE 


The following example extracts the public key from the certificate intmods.cer and creates a function named 
EISL_RetrieveSelfCheckKey () in the file modselfkey.h. 


S$ create intmodscertfile. 

intmods.cer 

$! 

S issuer -k intmodscertfile. modselfkey.h 
_S "EISL RetrieveSelfCheckKey" 


CDSA$MDS_INSTALL.EXE 


The mds _install utility is used to create (install) or delete (uninstall) the Module Directory Services database 
used by CDSA. 


This program generally is called by SYS$STARTUP:CDSAS$INITIALIZE.COM. 


SYNOPSIS 


mds_install [[-s source] [-d dbdest] ] [-u] 


OPTIONS 


NOTE OpenVMS users can specify only the -u option (or no option). However, the other options are 
described here for completeness for users who are accustomed to seeing them on another 
platform. 

-s source Specifies the MDS DLL source location (not used by OpenVMS). 


-d dbdest Specifies the destination file specification for the MDS database to be created. This 
parameter is currently hardcoded on OpenVMS, and should not be changed. 


-u Specifies that the operation is an uninstall of MDS, rather than an install. This parameter 
cannot be used with the -s and -d parameters. 


EXAMPLE 


The following command creates an empty CDSA MDS database. (If it is run against an already existing 
database, it does nothing.) 


mds_install 
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CDSA$MOD_INSTALL.EXE 


The mod_install utility is used to add information about CDSA modules into the Module Directory Services 
database. 


This program generally is called by SYS$STARTUP:CDSAS$INITIALIZE.COM. 


SYNOPSIS 
mod_install [-f] option [-s file] [-d path] 
OPTIONS 
-f Specifies not to warn about unsigned or corrupt modules. 
option Specifies the action to be taken by the mod_install utility: 
-i Install the module. 
-u Uninstall the module. 
-r Refresh the installation information. 
-S file Specifies the full file specification (in UNIX® directory format) of the source file to be 
installed. 
-d path Specifies the destination path (in UNIX directory format) of the source file to be installed. 
EXAMPLE 


The following example installs the add-in module stubcsp300_shr.exe in the CDSA MDS database. The 
logical definition in the first command is necessary because the shareable image is not in SYS$LIBRARY and 
it will be invoked as part of the installation process. 


S$ define stubcsp300_shr "cdsa_tempdir: [addin] stubcsp300_shr.exe" 
$ mod_install -i -s /cdsa_tempdir/addin -— 
_$ /stubcsp300_shr.exe -d /cdsa_tempdir/addin 


CDSA$S$OUTPUT_ERROR.EXE 


Note that this utility is defined as cdsa_error by CDSA$SYMBOLS.COM. The cdsa_error utility converts a 
CDSA numeric error code into its corresponding text strings. The text is output to SYS$OUTPUT. 


SYNOPSIS 


cdsa_error base_flag error_code 


OPTIONS 


base_flag The mathematical base in which the error code is represented: 
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-d Specifies that the numeric value of error_code is decimal (base 10). 
-0 Specifies that the numeric value of error_code is octal (base 8). 
-h Specifies that the numeric value of error_code is hexadecimal (base 16). 
If you specify something other than these options, you will get an error message that lists 
the correct options. (See Example 2.) 
error_code The error code stated in the numerical base specified by the base-flag parameter. 
EXAMPLES 


1.$ cdsa_error -h 3135 
Error: CSSMERR_DL_STALE_UNIQUE_RECORD 
The record returned has been changed by someone and is stale 


2.$ cdsa_error -? 
dka300: [sys0O.syscommon.] [sysexe] cdsaSoutput_error.exe;1: 


illegal option -- ? 

cdsaSoutput_error -djo|h <Error Code> 

options: 

-d : Error code is a decimal number 

-O : Error code is an octal number 

-h : Error code is a hexadecimal number 
CDSAS$SIGN.E XE 


Note that this utility is defined as cdsa_sign by CDSA$SYMBOLS.COM. The cdsa_sign utility takes a service 
provider product, application, or CSSM binary, plus the manufacturer certificates generated using certgen, 
and creates a manifest file. Manifest files have a file extension of .ESW. 


This utility can be used for Integrity signing and for Export signing. Integrity signing creates a new manifest, 
while Export signing adds signers to an existing manifest. The options for each function are totally different, 
so they are described here in separate sections. Integrity signing for a module must always be done before 
Export signing. 


Integrity Signing 
Integrity signing is optional for applications and mandatory for add-in modules. 


SYNOPSIS 


cdsa_sign module_name subdirectory type signer_cert password cert_chain 
module_guid access_tag pvcapi_tag pvcspi_tag priv_tag 


OPTIONS 
module_name Thenameof the module being signed. 
subdirectory Thesubdirectory (in UNIX directory format) containing the module being signed. 


type The module type, which can be one of the following: 
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signer_cert 
password 


cert_chain 


module_guid 


access_tag 


pvcapi_tag 


pvespi_tag 


priv_tag 
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Service provider module 
CSSM 

Application sharable image 
Elective Module M anager 


Generic file 


xoamouon > 


Application executable 

The name of the certificate being used to sign the module. 

The password for the private key of the certificate being used to sign the module. 

A text file identifying the certificates to be embedded. This file has the following form: 


number 
certl 
cert2 


where number is the number of certificates being embedded, and catl and cet2 are the 
names of certificates to be embedded; for example: 


2 
introot.cer 
intmanf.cer 


The string version of the globally unique identifier of the module being signed (as installed 
in MDS). 


For installer modules, this is the base-64 encoded, unsigned, 32-bit value (in big-endian) of 
the access type defined for CDSA_DB ACCESS TYPE. For modules other than installers, 
specify "XX" for this parameter. 


Specifies whether pointer validation checking is to be done on the application program 
interface boundaries. (Read more about PVC in “Pointer Validation Checking” on page 36.) 
The values for the CDSA_PVC_API tag areas follows: 


“EXEMPT” Specifies an application manifest, where the program can set the PVC flag 
in cssm_Init (). 

“OFF” Specifies a CSSM manifest, where the PVC flag is not applicable. 

“XX” Specifies that the CDSA_PVC_API tag is not in the manifest. 


Specifies whether pointer validation checking is to be done on the service provider interface 
boundaries. (Read more about PVC in “Pointer Validation Checking” on page 36.) The 
values for the CDSA_PVC_SPI tag areas follows: 


“EXEMPT” Specifies a service provider manifest, where the program can set the PVC 
flag in cssm_Init (). 

“OFF” Specifies a CSSM manifest, where the PVC flag is not applicable. 

“KX” Specifies that the CDSA_PVC_SPI tag is not in the manifest. 


The CDSA _PRIV tagin the manifest. NoCDSA_PRIV tag values are defined, so specify 
"XX" to indicate that this tag is not in the manifest. 
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EXAMPLE 


The following is an example of the cdsa_sign command for Integrity signing: 


S$ define cdsa_sign "/cdsa_tempdir/addin" 

$ set default cdsa_sysdir: [sign] 

S$ cdsa_sign stubcsp300_shr cdsa_sign A intmods.cer - 

_$ intmods intchain. {79BDEOF0-4541-11d3-A8F3-0090271D266F} - 
_$ "XX" "EXEMPT" "XX" "XX" 


The first command defines the logical cdsa_sign (which is used internally by the code) in UNIX directory 
format as the directory where the executable to be signed can be found. 


e — stubcsp300_shr is the name of the module being signed. 

e cdsa_sign is the logical pointing to the directory containing the module. 

e Aindicates that stubcsp300_shr is a service provider module 

e intmods.cer is the name of the certificate being used to sign the module. 

e intmods is the password for the private key of the certificate (intmods.cer) being used to sign the module. 
e jntchain. is the name of the text file containing the names of the certificates in the certificate chain. 
e {79B DE OF 0-4541-11d3-A8F 3-0090271D 266F }is the GUID of the service provider module. 

e "XX" is the access tag, which indicates that this is not an installer module. 

« "EXEMPT" is the CDSA PVC API tag specifying that this is an application manifest. 

« "XX" specifies that the CDSA_PVC_SPI tag is not in the manifest. 

« "XX" specifies that the CDSA_PRIV tag is not in the manifest. 


Export Signing 


Export signing is optional. Before you can do Export signing for a module, you must already have done 
Integrity signing and a manifest must exist. For more information about Export signing, refer to the Intd 
Common Data Security Architecture Manifest Signing Tools User’s Guide 


SYNOPSIS 


cdsa_sign manifest_path signer_cert password cert_chain usee_tag priv_tag pvcapi_tag 
pvespi_tag 


OPTIONS 


manifest_path The path (in UNIX directory format) to the manifest created in the Integrity signing phase. 
signer_cert The name of the certificate being used to sign the module. 


password The password for the private key of the certificate being used to sign the module. 
cert_chain A text file identifying the certificates to be embedded. This file has the following form: 
number 
certl 
cert2 
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usee_tag 


priv_tag 


pvcapi_tag 


pvespi_tag 


EXAMPLE 
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where number is the number of certificates being embedded, and cert 1 and cert2 are the 
names of certificates to be embedded; for example: 


2 
introot.cer 
intmanf.cer 


The base-64 encoded value of the CSSM_USEE_TAG value. This value must be enclosed 
within double quotation marks. 


The CDSA _PRIV tagin the manifest. NoCDSA_PRIV tag values are defined, so specify 
"XX" to indicate that this tag is not in the manifest. 


Specifies whether pointer validation checking is to be done on the application program 
interface boundaries. (Read more about PVC in “Pointer Validation Checking” on page 36.) 
The values for the CDSA_PVC_API tag are as follows: 


“EXEMPT” Specifies an application manifest, where the program can set the PVC flag 
in cssm_Init. 

“OFF” Specifies a CSSM manifest, where the PVC flag is not applicable. 

“XX” Specifies that the CDSA_PVC_API tag is not in the manifest. 


Specifies whether pointer validation checking is to be done on the service provider interface 
boundaries. (Read more about PVC in “Pointer Validation Checking” on page 36.) The 
values for the CDSA_PVC_SPI tag areas follows: 


“EXEMPT” Specifies a service provider manifest, where the program can set the PVC 
flag in cssm_Init. 

“OFF” Specifies a CSSM manifest, where the PVC flag is not applicable. 

“KX” Specifies that the CDSA_PVC_SPI tag is not in the manifest. 


The following is an example of the cdsa_sign command for Export signing: 


S$ cdsa_sign /cdsa_tempdir/des2/des2.esw exapps.cer secret exchain. - 
_s "ARAAAQ==" "YX" "RYXEMPT"™ "XX" 


In this example: 


e /cdsa_tempdir/des2/des2.esw is the path (in UNIX directory format) to the manifest created during 
Integrity signing. 


* exapps.cer is the name of the certificate being used to sign the module. 


e secret is the password for the private key of the certificate being used to sign the module. 


e exchain. is the name of the text file identifying the certificates to be embedded in the signature. 
« "AAAAAQ=" is the base-64 encoded value of the CDSA_USEE DOMESTIC tag. 

« "XX" specifies that the CDSA_PRIV tag is not in the manifest. 

« "EXEMPT" is the CDSA PVC API tag specifying that this is an application manifest. 

« "XX" specifies that the CDSA_PVC_SPI tagis not in the manifest. 
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CDSA$X5092XML .E XE 


The x5092xml utility reads an X509 certificate file, extracts the subject name, and writes the nameas XML to 
an XML file. This tool is useful for producing example template files that can be modified. 


SYNOPSIS 


x5092xml infile outfile 


OPTIONS 
infile 
The name of the X509 certificate file from which the subject name is being extracted. 
out file 
The name of the XML file to which the name is to be written. 
EXAMPLE 


x5092xml introot.cer introot.xml 
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4 CDSA Programming Concepts 


This chapter provides an overview of programming with CDSA on OpenVMS. This chapter should be read in 
conjunction with the Intel Common Data Security Architecture Application Devdoper's Guide the Intd 
Common Data Security Architecture Service Provider Devdoper’s Guide, and the | ntd Common Data Security 
Architecture Manifest Signing Tools User's Guide. 


This chapter covers the following topics: 


e An overview of building a CDSA application on OpenVMS (see “Overview of CDSA Programming on 
OpenVMS” on page 35) 


¢ Details about writing a signed CDSA application or add-in module (see “Writing Signed Applications” on 
page 36) 


e Steps to deploy signed applications and service provider modules ( see “Deploying Signed Applications 
and Service Provider Modules” on page 42) 


¢« Descriptions of the CDSA example programs (see “CDSA Example Programs” on page 42) 


¢ Information about CDSA errors and how to get a meaningful error return (See “CDSA Error Resolution” 
on page 49) 


Overview of CDSA Programming on OpenVMS 


CDSA programming on OpenVMS works much the same as on any other platform. The following sections 
indicate differences and important information. 


Compiling a CDSA Program 


CDSA V2.0 was built using Compaq C V6.5-001. HP recommends that applications or add-in modules be 
developed using the same compiler to avoid problems that could occur if the run-time library changes in 
another version. 


When you compile your program, you need to add the /INCLUDE=CDSA_SYSDIR:[INCLUDES] qualifier to 
your compiler command line. The following command is taken from the BUILD_DES.COM examplein this 
chapter (see “DES Encryption/Decryption Example Program” on page 43): 


$ CC/LIST/INCLUDE=CDSA_SYSDIR: [INCLUDES] /PREFIX=ALL DO_DES 


Linking a CDSA Program 


Most CDSA applications must link with SYS$SHARE:CDSA$I NCSSM 300 _SHR.EXE. If the application uses 
MDS, you might need to include SY S$SHARE :CDSA$MDS300 SHR.EXE and 
SYS$SHARE :CDSA$MDS_UTIL_API.OLB as well. 


Because CDSA routines are located in shareable libraries, the use of a link options file is recommended. For 
details about using link options files, refer to the OpenVMS Linker Utility Manual. The CDSA example 
programs described in “CDSA Example Programs” on page 42 provide examples of using link options files for 
CDSA applications. 
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CDSA Integrity Checking 


CDSA provides two types of integrity checking: bilateral authentication and pointer validation checking. 


Bilateral Authentication 


Bilateral authentication checks the integrity of modules as they are dynamically loaded into the system. A 
bilateral authentication procedure is designed for two entities to establish trust in the identity and integrity 
of each other. When loading a service provider module or an elective module manager, CDSA requires that the 
attaching module participate in this authentication protocol. Both modules in the bilateral authentication 
procedure must have signed credentials that bind them to the trust hierarchy used by CDSA. These 
credentials are stored in the CDSA MDS database during module installation. 


Refer to the Intel Common Data Security Architecture Application Developer's Guide (Chapter 11, Integrity) 
and the |ntd Common Data Security Architecture Manifest Signing Tools User's Guide for more detailed 
explanations of the bilateral authentication process. 

Pointer Validation Checking 

Pointer validation checking (PVC) entails validating addresses under the following circumstances: 


¢ Before calling across the application interface into CDSA (PVC is optional on OpenVMS in this case) 
¢ Beforecalling across the CDSA interface to an add-in module (PVC is required on OpenVMS in this case.) 


The Pointer Validation Policy is established using the PvcPolicy parameter in the CSSM_Init call. The 
parameter values can be derived using the constants in the file CSSMTYPE.H in 
CDSA_SYSDIR:[INCLUDES]. Starting with OpenVMS Alpha Version 7.3-2, the values for the PvcPolicy 
parameter that are valid for CDSA are as described in the following table. 


Value Description 


2 PVC validation is performed on service provider modules only. CSSM_PVC_SP is used for 
PVC validation on service provider modules. 


3 PVC validation is performed on both service provider and application modules. The bitwise 
OR of CSSM_PVC_APP and CSSM_PVC SP is used for PVC validation on both service 
provider and application modules; for example, (CSSM_PVC_APP | CSSM_PVC SP). 


For more information about pointer validation checking, see the description of the cSSM_Init() API. 


Writing Signed Applications 
Two types of applications can be developed to use CDSA integrity checking: 


¢ An application that calls into CDSA to use one or more of the services that it provides. 


CDSA applications developed on OpenVMS can optionally participate with CDSA in bilateral 
authentication. 


e Aservice provider module that “plugs-in” or “adds-in” to CDSA to provide a set of security related 
functions that an application program can in turn use. On OpenVMS, service provider modules are 
implemented as shareable images. 
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All CDSA add-in modules developed on OpenVMS must participate in bilateral authentication (see 
“Bilateral Authentication” on page 36) and pointer validation checking (see “Pointer Validation Checking” 
on page 36). 


The Intel Common Data Security Architecture Application Devdoper's Guideand the | ntd Common Data 
Security Architecture Service Provider Devd oper’s Guide have in-depth information about developing 
applications and add-in modules for CDSA. 


The development process includes generating certificates and key pairs to be used in the signing process and 
later in the integrity checking process. The public keys are extracted from the certificate into a code module 
that is included in the application. The private keys remain on the signing system. After the code is built, the 
certificate is used to “sign” the application or service provider module. The product of the signing isa 
manifest, which is typically kept with the executable. 


The following sections summarize the steps for building a signed CDSA application or add-in module on 
OpenVMS. 


The Signing Environment 


To create manifests used for authentication of CDSA modules, you must have a working version of CDSA and 
the signing tools installed on a machine. It is good practice to dedicate a specific machine or set of machines to 
be the signing center. Certificates for signing should be generated on the signing machine, and the signing of 
generated modules must be done there. The tools, applications, CDSA stack, and private keys used to 
generate certificates should not be modified or reinstalled after the certificate generation process has 
completed. Doing so will invalidate the keys used to make the certificates and will cause any modules signed 
to fail integrity checking. 


Development and testing of modules should be conducted on other machines so as not to disrupt the signing 
environment. 


The signing directory on an OpenVMS system is CDSA_SYSDIR:[SIGN]. 


On OpenVMS, the account that is used to create certificates must be the same account that is used for signing 
developed applications and service-provider modules. This is required because the private keys are stored in 
the namespace of that user account and must be accessible by the code performing those functions. Note that 
this account requires the SYSPRV privilege to access the signing directory. 


The Signing Tools 


The following programs are used in developing CDSA applications or add-ins: 


Program Name Description 


SY S$SYSTEM :CDSA$CERTGEN.EXE Certificate creation tool 


SY S$SYSTEM :CDSA$ISSUER.EXE Public key extraction tool 


SY S$SY STEM :CDSA$SIGN.E XE Signing tool 
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The following files in CDSA_SYSDIR:[SIGN] are named according to Intel naming conventions. Their names 
can be changed to suit any other development conventions. If the names introot.cer or intmanf.cer are 
changed, intchain must be updated to reflect the new names. The new certificate names will also be used as 


parameters to cdsa_sign. 


File Name Description 

introot.cer The CDSA Integrity Root certificate containing the public key of the root of the 
integrity chain. 

intmanf.cer The CDSA Integrity Manufacturing certificate containing the public key of the 


manufacturer. 


ssintapps.run 


The run file that is input to the certificate creation tool 
(CDSA$CERTGEN.EXE) to create a self-signed application certificate. 


ssintapps.xml 


The X509 formatted identification of the signer of the application certificate. 


ssintmods.run 


The run file that is input to the certificate creation tool 
(CDSA$CERTGEN.E XE) to create a self-signed add-in module certificate 


ssintmods.xml 


The X509 formatted identification of the signer of the add-in module certificate 


intchain. 


A list of certificates comprising the integrity certificate chain; that is, 
introot.cer and intmanf.cer 


Thefile CDSA_SYSDIR:[SIGN ]JCDSA$GEN_CERTS.COM is used to generate the digital certificates and 
keypairs that are used by CDSA applications. 


The Signing Process 


The first five of the following nine steps need to be done only once for each application or add-in module being 
developed. However, each time the application is changed, a new manifest must be created and the 
application must be reinstalled in the CDSA MDS database (steps 8 and 9). 


If you are building the example programs provided with CDSA Version 2.0 or later, some of the following 
steps have been done in example code or accompanying command procedures. Read 
SYS$COMMON [SY SHLP.EXAMPLES.CDSAJREADME.TXT for details. 


1. Generate a GUID. 


Each signed application and service provider module should have a global unique identifier (GUID). This 
GUID should be written to a header file in the application development directory — either as an 
individual header file or included in another header file. (See the model in DESGUID.H in the DES2 or 
DES3 examples: “DES2 Encryption/Decryption Example Program” on page 45 or “DES3 Example 


Program” on page 46.) 


If your development environment is OpenVMS Version 7.3-2 or higher, you can simply execute the GUID 
generating command procedure in CDSA_SYSDIR:[SIGN] and the procedure will output a GUID as 
shown in the following example: 


$ @CDSA_SYSDIR: [SIGN] CDSASUUIDGEN 


XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX 


The string form of the GUID is used as input to the signing tool, CDSA$SIGN.E XE, when the application 
or add-in module is signed. 


The string form of a GUID is expressed as follows: 
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" {FD52A3EA-D9EC-1159-916B-08002BC48051}" 
The numeric form of the same GUID (as defined by the data structure CSSM_GUID) would be: 


{Oxfd52a3ea, 

Oxd9ec, 

0x1159, 

{0x91, Ox6b, 0x08, 0x0, OxZ2b, Oxc4d, 0x80, Ox51}} 


Add a GUID variable pointer to the calls to cssm_Init () and, if you are using them, to 
CSSM_Introduce() and CSSM_Unint roduce (). 


NOTE If you are developing on a system earlier than OpenVMS Version 7.3-2, you must find 
another method to generate a GUID that conforms to the preceding format. 


. Generate a Certificate. 


The first step in the process of creating credentials is to generate a self-signed certificate by running 
CDSA$CERTGEN.EXE. This is always done on the signing system. The default directory must be set to 
CDSA_SYSDIR:[SIGN] and the user must have read/write access to this directory. (Steps 3 and 8, 
generating the key and the manifest, must also be done in this directory.) 


This step produces a private key and a public key for the application. The private key always remains on 
the signing system. The matching public key is embedded in the generated certificate. 


A .RUN fileand an .XML file are input to CDSA$CERTGEN.EXE. The following samples of these files 
can be found in CDSA_SYSDIR:[SIGN]: 


e ssintapps.run and ssintapps.xml (input to generate an application certificate) 
e —ssintmods.run and ssintmods.xml (input to generate a service provider module certificate) 


The .RUN file contains input to the certificate generation process, including the name of the .XML file. 
The .XML file contains attributes to identify the issuer of a certificate in machine-readable X500 format. 
The following table shows the attributes that are used. The attribute name is not used in the .XML file 
but is included in the table for human readability. Note that only one value is specified for each attribute 
in the .XML file 


Attribute OID Attribute Name Example Value OpenVMS Value 

2.5.4.3 Common Name Senior Technician H ewlett-Packard 

2.5.4.10 Organization Name XYZ Company BCS (Business Critical 
Servers) 

2.5.4.11 Organizational Unit ABC Division OpenVMS 

Name 

2.5.4.1 Aliased Entry Name XYZ Security Product | HP OpenVMS Integrity Root 

2.5.4.9 Street Address 110 Maple Street 110 Spit Brook Road 

2.5.4.7 Locality Anytown Nashua 

2.5.4.8 State or Province XX NH 

2.5.4.6 Country USA USA 

2.5.4.17 Postal Code 54321 03062 
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Attribute OID Attribute Name Example Value OpenVMS Value 
2.5.4.23 Telephone Number 777-666-4321 (not used) 
1.2.840.113549.1.9.1 | Email Address role@xyz.com OpenVM SSecurity@hp.com 
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Make the desired changes to the attributes in the .XML file to identify the issuer of the certificates. 
Chapter 3 of the |Inted Common Data Security Architecture M anifest Signing Tools User's Guide explains 
the XML syntax used here. 


You can run CDSA$CERTGEN.EXE by itself or you can execute the command procedure 
CDSA_SYSDIR:[SIGNJCDSA$GEN_CERTS.COM torun both CDSA$CERTGEN.EXE to generate a 
certificate and CDSA$ISSUER.EXE to generate the key code (see Step 3). 


. Generate Key Code. 


CDSA$ISSUER.EXE generates the code that embeds the public key in the application. You can run this 
program by itself in directory CDSA_SYSDIR:[SIGN] or you can let it execute as part of 
CDSA_SYSDIR:[SIGNJCDSA$GEN_CERTS.COM. CDSA$ISSUER.EXE extracts the public key into a C 
structure to be included in the developed program. It generates two certificates, ssintapps.cer and 
ssintmods.cer. 


Because the generated certificates are self-signed, they also need to be signed with the private key of the 
root of the integrity certificate chain being used for CDSA. This root is the private key originally 
generated by OpenVMS. This certificate signing is accomplished by sending email to 
OpenVMSSecurity@hp.com. The response will provide details on how to proceed with having your 
certificates signed by the OpenVMS integrity root. 


CDSA$ISSUER.EXE also generates the following include files: 
e APPSELFKEY.H (used to develop an application) 
¢ MODSELFKEY.H (used to develop a service provider module) 


Copy these two files into the application development area. 


. Generate SelfCheck code. 


For an application: 


As part of the self-check process, you must modify the following three procedures in the CALLOUTS.C 
module found in each CDSA example directory: 


e EISL_RetrieveSelfCheckSectionName () 


e EISL_ RetrieveSelfCheckCredentials () 


e EISL_ RetrieveSelfCheckCredentialsSize () 


Modify these procedures to use the application GUID in calls to mdsutil_GetModuleCredentialiInfo(). 
In the DES2 and DES3 examples in this chapter (see “DES2 Encryption/Decryption Example Program” 
on page 45 and “DES3 Example Program” on page 46), the application GUID is defined by including a file 
called DESGUID.H. 


Define the constant SECTION to be the name of the application executable. 
CALLOUTS.H contains function prototypes for all the self-check procedures that will be invoked. 


For an add-in module: 
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Change the definition of ADDIN_SELF_CHECK_SECTION in the MAF_CONFIG.H module in the 
example directory to the name of the shareable image (with no extension). 


5. Add CDSA procedures to the Application. 


Before making any calls to CSSM, insert a call to EISL_SelfCheck () to validate the integrity of the 
application itself. After a successful return, call EISL_RecycleVerifiedModuleCredentials () torelease 
the structures that were created. 


If you want to ensure the integrity of CDSA, you can load it dynamically and let the code perform 
integrity checking on it before any CSSM code is executed. One way to do this is by using the Application 
Adaptation Layer. All code to use this layer is provided in the DES3 example program. Call 
AALProxyLoadCssm() after EISL_SelfCheck (), and before making any calls toCSSM. 


If you want to perform pointer validation checking across the API boundary, you must call the APIs in the 
following order so that the necessary data structures are set up: 


* CSSM_Init () 

° CSSM_Introduce () 

¢ CSSM_ModuleLoad () 

When processing ends, the application should call cSSM_Unintroduce () (if you used it) before calling 
CSSM_Terminate() and then AALProxyUnloadCssm(). 


CDSA Add-in Modules 


The integrity checking process for add-in modules is provided by the Multi-service Add-in Framework. In 
fact, the MAF *.* modules provide a framework for developing an add-in module. 


Development of a CDSA service provider add-in module is beyond the scope of this document. The 
OpenVMS CDSA example application ADDIN illustrates the development of a Cryptographic Service 
Provider add-in module. The Inte Common Data Security ArchitectureServiceProvider Developer's Guide 
provides complete details for developing an add-in module for CDSA. 


6. Compile and link the application or add-in module. 
7. Build the code to install the application. 


A service provider module can be installed in the CDSA MDS database using 
SYS$SYSTEM:CDSA$MOD_INSTALL.EXE. 


An application must build a program to perform the installation. The two signed example applications 
DES2 and DES3 include an installation program that demonstrates the basics of installing an 
application. 


8. Generate the manifest. 


In directory CDSA_SYSDIR:[SIGN] on the signing system, sign the application by generating a set of 
credentials. The application credentials are contained in a manifest, application.E SW, which 
accompanies the application. | nput to the credential generation includes the application executable and 
the certificate being used to sign the application. For more details, refer to the Intel Common Data 
Security Architecture Manifest Signing Tools User's Guide. 


Each of the example programs described in this chapter includes a procedure called example SIGN.COM 
that demonstrates how to generate a manifest. 


The manifests are typically kept with the application executable. 
9. Install the application in the CDSA MDS database. 
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Each of the example programs includes code that produces an application program and a procedure called 
example_INSTALL.COM that demonstrates how to install an application in the CDSA MDS database. 


Deploying Signed Applications and Service Provider Modules 


To deploy a CDSA signed application or service provider module, you must deliver the following items to the 
system where they are to be used: 


¢ Theexecutable 


e Themanifest (£i1ename.E SW) containing the credentials of the executable 


e« Theinstallation program (for an application, a service provider module can use 
CDSA$MOD_INSTALL.EXE) 


After the files arein place, run the installation program. 


CDSA Example Programs 


Seven example programs are provided with CDSA Version 2.0 on OpenVMS. Command procedures to build, 
sign, and install them are provided along with individual README files for each example. 


The following table lists the example programs and describes what aspect of CDSA each program is designed 


to convey. 
Example Program Signed | Description Section 
DES No Simple DES encryption/decryption “DES Encryption/Decryption 
program Example Program” on 
page 43 
MDS No Program to query MDS database for “MDS Example Program” on 
CDSA services page 44 
DES2 Yes DES example with integrity checking, | “DES2 
explicitly linked Encryption/Decryption 
Example Program” on 
page 45 
DES3 Yes DES example with integrity checking, | “DES3 Example Program” on 
using AAL (dynamically loaded) page 46 
ADDIN Yes An add-in module written totheCSP | “ADDIN Example Program” 
Service Provider Interface, with on page 46 
integrity checking 
DUMMYEMM Yes An Elective Module Manager to “DUMMYEMM Example 
define a new Service Provider Program” on page 47 
Interface, wtih integrity checking 
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Example Program Signed | Description Section 
DUMMYEMMADDIN | Yes An add-in module written to the SPI “DUMMYEMMADDIN 
made availableby DUMMYEMM, Example Program” on 
with integrity checking page 48 


Before you build the example programs, please read the following README files: 
¢ For an overview of all the CDSA examples: SYS$¢COMMON:[SY SHLP.E XAMPLES.CDSAJREADME.TXT 


e For details about an individual example program, see the README filein each example directory. For 
example, the README file for DES is in the following location: 
SYS$COMMON:[SY SHLP.EXAM PLES.CDSA.DES]JREADME.TXT 


You must initialize CDSA before running any example program. For the initialization procedure, see “CDSA 
Version 2.0 Setup and Initialization” on page 20. 


Pay special attention to “Writing Signed Applications” on page 36 if you plan to build one of the signed 
examples or are developing a CDSA add-in module. 


The examples are designed to be organized under a local build area or directory such as 
disk:[directory.example]. 


Define the rooted logical CDSA_TEMPDIR as disk:[directory.] using the following command: 


$ DEFINE/TRANSLATION=CONCEALED CDSA_TEMPDIR disk: [directory.] 


Under this directory, the command procedures expect to find individual directories for each example; for 
example: 


DISK1: [EXAMPLES .DES] 
DISK1: [EXAMPLES .MDS] 
DISK1: [EXAMPLES .DES2] 


DES Encryption/Decryption Example Program 


This example is a simple DES encryption/decryption program that uses CDSA with no integrity checking. It 
links explicitly against CDSA$I NCSSM300_ SHR.EXE. 


The DES example includes two source files (DES.C and DO_DES.C) and two build files (BUILD_DES.COM 
and DES.OPT). 


Copy the example files into a local build area and then execute the BUILD_DES command file, as follows: 


S COPY SYSSSYSROOT: [SYSHLP.EXAMPLES.CDSA.DES]*.* disk: [directory.DES] 
S SET DEFAULT disk: [directory.DES] 
$ @BUILD_DES 


It is easiest to run the resulting DES.EXE file as a foreign command. Define a symbol for this command as 
follows: 


S DES :== $ disk: [directory.DES]DES.EXE 


You can now execute the program using any of the following applicable options: 


Option Description 
-e Encrypt with supplied key (requires -k option) 
-d Decrypt with supplied key (requires -k option). 
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Option Description 
-k "key" Supplies a key, which must be enclosed within double quotation marks if it is ASCII 


and case sensitive; no quotation marks are allowed for hexadecimal numbers. 


-h The supplied key is a 16-character hexadecimal number. 


For example, to encrypt MYFILE.TXT using an ASCII key with the DES example program, enter the 
following command using double quotation marks, as shown, if the Key is case sensitive: 


$ DES -e -k "xyzzy" MYFILE.TXT MYFILE.DES 


To decrypt the same file, enter the following command: 


$ DES -d -k "xyzzy" MYFILE.DES MYFILE.TXT 


To encrypt or decrypt with a hexadecimal key, use the -h option and make sure the key length is exactly 16 
typed characters (8 hexadecimal bytes). No quotation marks, either single or double, are allowed. For 
example, 


$ DES -e -k 012abcde01l2abcde -h MYFILE.TXT MYFILE.DES 


$ DES -d -k 012abcde012abcde -h MYFILE.DES MYFILE.TXT 


MDS Example Program 


This program uses some of the MDS and CSSM services of CDSA, with nointegrity checking. It links 
explicitly against CDSA$INCSSM300 SHR.EXE. 


The MDS example includes two source files (DECODE_CDSA_ERRORS.C and MDS_EXAMPLE.C) and two 
build files (BUILD_MDS_EXAMPLE.COM and MDS_EXAMPLE.OPT). 


The program follows the descriptions and code fragments from the |ntd Common Data Security Architecture 
Application Devd oper's Guide. 


Build the MDS example program by copying the example files into a local build area and then executing the 
BUILD_MDS_EXAMPLE command file, as follows: 


$ COPY SYSSSYSROOT: [SYSHLP.EXAMPLES.CDSA.MDS]*.* disk: [directory.MDS] 
S SET DEFAULT disk: [directory.MDS] 
$ @BUILD_MDS_EXAMPLE 


Theresulting MDS_EXAMPLE.EXE file takes no parameters and can be executed as follows: 


S$ RUN disk: [directory.MDS]MDS_EXAMPLE 


The following is an excerpt of output from the program: 


S RUN MDS_EXAMPLE.EXE 

Module 0) Name: SSLeay Crypto Based CSP 

Module 0) ModuleGuid: {67ef50d0-fe74—-11d2-a8e6—-0090271d266f} 
Module 0) Version: 3.1 

Module 0) CompatibleCSSMVersion: 2.1 

Module 0) Description: SSLeay Crypto Based CSP 

Module 0) Vendor: Hewlett-Packard Company 

Module 0) Flags: 0x0 

Module 0) ServiceMask: 0x2 


Service 0) Description: SSLeay Crypto Based CSP 
Service 0) Type: CSSM_SERVICE_CSP 
Service 0) Flags: 0x0 
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SubService 0) 
SubService 0) 


This is a SOFTWARE subservice wi 
pe: CSSM_ALGCLASS_RANDOMG 
Type: CSSM_ALGID_M 
ute Type: CSSM_A 
Type: CSSM_A 
pe: CSSM_ALGCLASS_|! 
CSSM_ALGID 
ute Type: CSSM_A 
ute Type: CSSM_A 


Context Ty 
Algorithm 
Attrib 
Attrib 
Context Ty 
Algorithm 
Attrib 
Attrib 


Service 0) Descr 


Service 0) Type: 
Service 0) Flags 


ModuleType: 0 
SubServiceld: 


ute 


Type: 


0 


= 
EN 


th 30 capabilities 


D5Random 
RIBUTE_BLOCK_SIZE 
RIBUTE_DESCRIPTION 
DIGEST 

| MD5 
RIBUTE_OUTPUT_SIZE 
RIBUTE_DESCRIPTION 
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Name: CDSA Adaptation Layer CSP for the BSafe Toolkit from RSA DSI 
id: {d6b5e822-£376-11d3-9bea-0008c74fe165} 


ion: CDSA Adaptation Layer CSP for the BSafe Toolkit from RSA 


Hewlett-Packard Company 


Module 1) 
Module 1) ModuleGu 
Module 1) Version: 3.1 
Module 1) CompatibleCSSMVersion: 
Module 1) Descript 
DSI 
Module 1) Vendor: 
Module 1) Flags: 0x0 
Module 1) ServiceMask: 0x2 


iption: CDSA Adaptation Layer CSP for the BSafe Toolkit from RSA 
DSI 
CSSM_SERVICE_CSP 


: 0x0 


SubService 0) ModuleType: 0 


SubService 0) 


This is a SOFTWAR 


SubServiceld: 


Context Type: CSSM_ALGC 


Algorithm Type: 


0 


E subservice with 33 capabilities 


iASS_RANDOMGEN 
Algorithm Type: CSSM_ALGID_MD2Random 
Attribute Type: CSSM_ATTRIBUTE_DESCRIPTION 
Context Type: CSSM_ALGCLASS_RANDOMGEN 
CSSM_ALGID_MD5Random 
Attribute Type: CSSM_ATTRIBUTE_DESCRIPTION 


DES2 Encryption/Decryption Example Program 


The DES2 example program is nearly identical to the DES example except that it uses integrity checking in 
addition to the encryption/decryption CDSA calls. It links explicitly against CDSA$INCSSM 300 SHR.EXE. 


This example is designed to be signed using the CDSA signing tools. 


The necessary files to build the example on OpenVMS are included, with the exception of APPSELFKEY.H. 


This include file must be generated from the certificate created for the application. 


See “Writing Signed Applications” on page 36 for complete instructions. A signed CDSA application will not 
execute until the proper credentials are generated. 


After you generate the application credentials and the include file APPSELFKEY.H, you can build the DES2 
example program by copying the example files into a local build area and executing the DES2 BUILD 
command file, as follows: 
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$ DEFINE/TRANS=CONCEALED CDSA_TEMPDIR disk: [directory.] 
$ SET DEFAULT CDSA_TEMPDIR: [DES2] 

$ COPY SYSSSYSROOT: [SYSHLP .EXAMPLES.CDSA.DES2]*.* [] 

$ COPY CDSA_SYSDIR: [SIGN]APPSELFKEY.H [] 

$ @DES2_BUILD 


Theresulting image, DES2.E XE, must be signed. On the signing system, run the following command 
procedure to generate the manifest: 


$ @DES2_SIGN 


Finally, on the development system, run the command procedure to install the module, as follows: 


$ @DES2_INSTALL 


It is easiest to run the application DES2.E XE file as a foreign command. Define a symbol for this command as 
follows: 


$ DES2 :== SCDSA_TEMPDIR: [DES2]DES2.EXE 


The options and program usage are the same as for the DES example. 


DES3 Example Program 


The DES3 example program is nearly identical to the DES2 example except that it links dynamically at 
run-time against CDSA$INCSSM 300 SHR.EXE using the CDSA Application Adaption Layer. 


This example is designed to be signed using the CDSA signing tools. 


The files necessary to build the example on OpenVMS are included, with the exception of APPSELFKEY.H. 
This include file must be generated from the certificate created for the application. 


See “Writing Signed Applications” on page 36 for complete instructions on writing a signed application. A 
signed CDSA application will not execute until the proper credentials are generated. 


After you generate the application credentials and the include file APPSELFKEY.H, you can build the DES3 
example program by copying the example files into a local build area and executing the DES3 BUILD 
command file, as follows: 


DEFINE/TRANS=CONCEALED CDSA_TEMPDIR disk: (directory. ] 
SET DEFAULT CDSA_TEMPDIR: [DES3] 

COPY SYSSSYSROOT: [SYSHLP .EXAMPLES.CDSA.DES3]*.* [] 
COPY CDSA_SYSDIR: [SIGN]APPSELFKEY.H [] 


nnn nH 


@DES3_BUILD 


The resulting image, DES3.EXE, must be “signed”. On the signing system, run the following command 
procedure to generate the manifest: 


$ @DES3_SIGN 


Finally, on the development system, run the command procedure to install the module, as follows: 


$ @DES3_INSTALL 


It is easiest to run the resulting DES3.EXE file as a foreign command. Define a symbol for this command as 
follows: 


S DES3 :== $ disk: [directory]DES3.EXE 


The options and usage of the program are the same as for the DES example. 


ADDIN Example Program 


The ADDIN example shows how to provide a new add-in for an existing category of service. 
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This CDSA example is an add-in (plug-in) module written to the CDSA CSP service provider interface with 

integrity checking. The add-in would be “loaded” and “attached” by an application, as in the DES examples, 

using CSSM_ModuleLoad (), CSSM_ModuleAttach(), and so forth. This example demonstrates the mechanics 
of developing a CDSA add-in module, which is a shareable image on OpenVMS. 


This example also provides the CDSA code files that are necessary to build an add-in module. The installation 
procedure registers the module in the CDSA MDS database, including its credentials, properties, and 
capability attributes. It attaches the module and executes RegisterCDSAModule () (the definition of 
INSTALL_ENTRY_NAME). 


The files necessary to build the example on OpenVMS are included, with the exception of MODSELFKEY.H. 
This include file must be generated from the certificate created for the add-in module. 


See “Writing Signed Applications” on page 36 for complete instructions on writing a signed application. A 
signed CDSA application will not execute until the proper credentials are generated. 


After you generate the application credentials and the include file MODSELFKEY.H, you can build the 
ADDIN example program by copying the example files to a local build directory and executing the 
ADDIN_BUILD command file, as follows: 


$ DEFINE/TRANS=CONCEALED CDSA_TEMPDIR disk: [directory.] 
$ SET DEFAULT CDSA_TEMPDIR: [ADDIN] 

$ COPY SYSSSYSROOT: [SYSHLP .EXAMPLES.CDSA.ADDIN]*.* [] 

$ COPY CDSA_SYSDIR: [SIGN]MODSELFKEY.H [] 

$ @ADDIN_BUILD 


The resulting shareable image, STUBCSP300 SHR.EXE, must be signed. On the signing system, run the 
following command procedure to generate the manifest: 


$ @ADDIN_SIGN 
Finally, on the development system, run the command procedure to install the module, as follows: 
$ @ADDIN_INSTALL 


The add-in module is now ready to be invoked by an application program. 


DUMMY Example Programs 


The DUMMYEMM and DUMMYEMMADDIN programs together demonstrate how to provide a new category 
of service for CDSA. DUMMYEMM,, an elective module manager (EMM), contains the logic for handling the 
generic types of operations for the new service, and the add-in (DUMMYEMMADDIN) contains logic that is 
specific to the particular operation being performed. 


TheADDIN example (see the “ADDIN Example Program” on page 46) shows how to provide a new add-in for 
an existing category of service DUMMYEMM and DUMMYEMMADDIN are designed to provide an entirely 
new category of service. 


DUMMYEMM Example Program 


This CDSA example is an elective module manager (EMM) that extends the functionality of CDSA by 
providing an additional category of service. The example defines a new service provider interface (SPI) with 
integrity checking. 


The purpose of this example is to demonstrate the mechanics of developing a CDSA EMM, which isa 
shareable image on OpenVMS. The example also provides the CDSA code files that are necessary to build an 
EMM. 
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The installation procedure registers the module in the CDSA MDS database, including its credentials, 
properties, and capability attributes. It attaches the module and executes RegisterCDSAModule () (the 
definition of INSTALL_ENTRY_NAME). 


The files necessary to build the example on OpenVMS are included, with the exception of MODSELFKEY.H. 
This include file must be generated from the certificate created for the add-in module. 


Refer to “Writing Signed Applications” on page 36 for complete instructions on writing a signed application. A 
signed CDSA application will not execute until the proper credentials are generated. 


After you generate the application credentials and the include file MODSELFKEY.H, you can build the 
DUMMYEMM example program by copying the example files to a local build directory and executing the 
DUMMYEMM_BUILD command file, as follows: 


$ DEFINE/TRANS=CONCEALED CDSA_TEMPDIR disk:[directory.] 
$ SET DEFAULT CDSA_TEMPDIR: [DUMMYEMM] 

$ COPY SYSSSYSROOT: [SYSHLP.EXAMPLES.CDSA.DUMMYEMM]*.* [] 
$ COPY CDSA_SYSDIR: [SIGN]MODSELFKEY.H [] 

$ @DUMMYEMM_BUILD 


The resulting shareable image, DUMMYEMM_SHR.EXE, must be signed. On the signing system, run the 
following command procedure to generate the manifest: 


S$ @DUMMYEMM_SIGN 


Finally, on the development system, run the command procedure to install the module, as follows: 


$ @DUMMYEMM_INSTALL 


When an application program loads an add-in module that is written tothe SPI of this EMM, the EMM will 
be automatically loaded. 


DUMMYEMMADDIN Example Program 


This CDSA example is an elective module manager (EMM) that extends the functionality of CDSA by 
providing an additional category of service. It provides an add-in module with integrity checking, written to 
the SPI made available by the DUMMYEMM example. 


The purpose of this example is to demonstrate the mechanics of developing a CDSA service provider module 
for a category of service defined by an EMM. It also provides the necessary CDSA code files that are necessary 
to build the module. 


The installation procedure registers the module in the CDSA MDS database, including its credentials, 
properties, and capability attributes. It attaches the module and executes RegisterCDSAModule () (the 
definition of INSTALL_ENTRY_NAME). 


The files necessary to build the example on OpenVMS are included, with the exception of MODSELFKEY.H. 
This include file must be generated from the certificate created for the add-in module. 


See “Writing Signed Applications” on page 36 for complete instructions on writing a signed application. A 
signed CDSA application will not execute until the proper credentials are generated. 


After you generate the application credentials and the include file MODSELFKEY.H, you can build the 
DUMMYEMMADDIN example program by copying the example files to a local build area and executing the 
DUMMYEMMADDIN_BUILD command file, as follows: 


$ DEFINE/TRANS=CONCEALED CDSA_TEMPDIR disk:[directory. ] 
SET DEFAULT CDSA_TEMPDIR: [DUMMYEMMADDIN] 
$ COPY SYSSSYSROOT: [SYSHLP.EXAMPLES.CDSA.DUMMYEMMADDIN]*.* [] 
$ COPY CDSA_SYSDIR: [SIGN]MODSELFKEY.H [] 
$ @DUMMYEMMADDIN_BUILD 
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The resulting shareable image, DUMMYEMMADDIN_SHR.EXE, must be signed. On thesigning system, run 
the following command procedure to generate the manifest: 


$ @DUMMYEMMADDIN_SIGN 


Finally, on the development system, run the command procedure to install the module, as follows: 


$ @DUMMYEMMADDIN_INSTALL 


The add-in module is now ready to be invoked by an application program. 


CDSA Error Resolution 


The CDSA implementation on OpenVMS supplies a special program that can be used to translate numeric 
CDSA error codes to text messages. This program resides in the SYS$SYSTEM directory and is called 
CDSA$OUTPUT_ERROR.EXE. It uses the routines described in this section to convert a numeric error code 
to its associated text label and error string. A foreign command, cdsa_error, has been defined in 
SYS$MANAGE R:CDSA$SY MBOLS.COM to invoke this program. For details about using cdsa_error and its 
options, see Chapter 3, “CDSA Utility Programs,” on page 25. 


The MDS example program provides two special routines for deciphering CDSA error codes within a user 
program. Because the CDSA include file that specifies error codes 
(CDSA_SYSDIR:[INCLUDES]JCSSMERR.H) does not allow for easy translation from the numeric code to the 
associated error string, these routines can make the job of debugging a CDSA application easier. These 
routines are: Decode_CDSA_Error() and Print_CDSA_Error(). 


They are described in the following sections. 


Decode _CDSA Error() 


This function accepts a CDSA numeric error code and returns two strings: the ASCII name of the error anda 
description of the error. 


SYNOPSIS 


#include <cssmerr.h> 


API: 


void Decode_CDSA_Error (Error_Code, Error_Label_String,Error_String) 
CSSM_RETURN Error_Code; 
char *Error_Label_String; 
char *Error_String; 


RETURN VALUE 


None 
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Print_CDSA Error() 


This function accepts a CDSA numeric error code, calls Decode_CDSA Error, and prints the resulting strings 
to SYS$OUTPUT. 


SYNOPSIS 


#include <cssmerr.h> 


API: 


void Print_CDSA_Error (Error_Code) 
CSSM_RETURN Error_Code; 


RETURN VALUE 


None 
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This reference section contains descriptions of the CDSA API functions. 


These descriptions are also available from online help. To access help, enter the HELP CDSA command at the 
system prompt. 


The MDSUTIL API functions area special group of functions described in the following paragraphs. 


MDS Utility Library API Functions 


Although the MDS API is a required part of any CDSA implementation, the MDSUTIL functions are not. 

This library of functions was provided with the Intel CDSA reference implementation to encapsulate many 
common queries that applications typically make to MDS. CDSA on OpenVMS implements the Intel CDSA 
version of the MDS utility library. Other vendors may supply their own utility libraries built on top of MDS. 


To use the MDS utility library, you must include two header files, MDS UTIL_API.H and 
MDS_UTIL_HELPER.H, which arein the CDSA_SYDIR:[INCLUDES] directory. You must also link with the 
library files CDSA$MDS300 SHR.EXE and CDSA$MDS_UTIL_API.OLB, which arelocated in SYS$SHARE. 


For further information, see the Inta€ Common Data Security Architecture Application Devdoper's Guide 
Chapter 2 (Module Directory Services), under the heading MDS Utility Library. 
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NAME 
AC_AuthCompute - Compute authorization (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMACI CSSM_AC_AuthCompute 
(CSSM_AC_HANDLE ACHandle, 

const CSSM_TUPLEGROUP *BaseAuthorizations, 
const CSSM_TUPLEGROUP *Credentials, 

uint32 NumberOfRequestors, 

const CSSM_LIST *Requestors, 

const CSSM_LIST *RequestedAuthorizationPeriod, 
const CSSM_LIST *RequestedAuthorization, 


CSSM_TUPLEGROUP_PTR AuthorizationResult) 


Seis 
CSSM_RETURN CSSMACI AC_AuthCompute 
(CSSM_AC_HANDLE ACHandle, 

const CSSM_TUPLEGROUP *BaseAuthorizations, 
const CSSM_TUPLEGROUP *Credentials, 

uint32 NumberOfRequestors, 

const CSSM_LIST *Requestors, 

const CSSM_LIST *RequestedAuthorizationPeriod, 
const CSSM_LIST *RequestedAuthorization, 


CSSM_TUPLEGROUP_PTR AuthorizationResult) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


ACHandle (input) 


The handle that describes the authorization computation module used to perform this 
function. 


BaseAuthorizations (input) 


A pointer toa CSSM_TUPLEGROUP containing at least one ACL certificate, specifying the 
authorization granted to certain root keys, named entities or combinations thereof. A NULL 
group of BaseAuthorizations always results in aNULL AuthorizationResult. 


Credentials (input/optional) 


A pointer toa CSSM_TUPLEGROUP containing a group of certificates, in TUPLE form. 
The tuple-certificates define the delegation of authorizations from the BaseAuthorizations 
to the Requestors. If no additional authorization-granting tuples are provided, then this 
value is NULL and the BaseAuthorizations are the only source of trusted authorizations 
used as input to the authorization computation. 


NumberOfRequestors (input) 
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The number of entries in the Requestors array. 
Requestors (input) 


A pointer toa list of requestors that define the "who" portion of the request. The list can be 
of type CSSM_LIST_TYPE_SEXPR. Typical exhibits include: 


e Public keys 

e Hashes of keys 

e« Hashes of other objects offered for proof. 
RequestedAuthorizationPeriod (input/optional) 


A list defining a validity period or NULL (implying “all time"). This is the "when" portion of 
the request. 


If the list is of type CSSM_LIST_TYPE_SEXPR, then the validity interval is specified as a 
two-element list containing the values ((not-before <datel>)(not-after <date2 >)). Note that 
each element is a two-element sublist. The <date>is represented by an ASCII byte-string, 
in the format (for example) "1998-11-24 15:06:16" and is assumed to be GMT. Open-ended 
timeintervals are specified by omitting either of the interval ends. For example, ((not-before 
1997-1-1_00:00:0)) specifies all dates and times beginning on J anuary 1, 1997 going forward 
indefinitely. For programming convenience, when testing for authorization at a single point 
in time, the date is represented by a one-element list containing (<date>). 


RequestedAuthorization (input) 
A list defining the "what" portion of the authorization being requested. 


If the list is of type CSSM_LIST_TYPE_SEXPR, then thelist presents an authorization 
request in SPKI format. If a specific authorization is being requested, then this input is a 
two-element SE XPR list containing (tag <req>). The valid values for <req>are 
application-specific. If this is a request to derive all possible authorizations based on the 
BaseAuthorizations, Credentials, and Requestors, then this input value must be the 
two-element list containing (tag (*)). This list corresponds to "all authorizations". With this 
input, the function tests the provided ACL and certificates against the Requestors (and 
possibly RequestedAuthorizationPeriod) to yield all authorizations for which the 
provided Exhibits qualify. 


AuthorizationResult (output) 


A CSSM_TUPLEGROUP structure, giving the result of the authorization computation. 
Typically there will be one result, but there could be as many as there are entries in the 
BaseAuthorizations. Each of these results says, in effect: "for this machine, under this 
ACL and the provided certificates, relative to the specified Requestors, the following 
authorizations have been deduced". Those authorizations are available only on the current 
platform (and possibly only for the application providing the ACL), and are therefore in the 
form of an ACL. They are not intended to be used by any other machine or application 
instance, necessarily, and need to be converted into certificates signed by some private key 
available to the caller if they are to be so used. 


DESCRIPTION 


This function performs an authorization computation and returns the results as a group of tuple certificates. 
The computation is based on the following input values: 


Requestors 
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One or more items that identify the requestor. These items are matched against subject 
fields in BaseAuthorizations or Credentials. These will be of any form that occurs in an 
ACL or certificate, and the class of entries is extensible. AuthCompute uses these fields to 
compare against Subject fields of TUPLES but does not interpret them, so it does not need 
to be aware of these extensions. Requestors, taken together with 
RequestedAuthorization and RequestedAuthorizationPeriod, form request tuples of 
the form "who requests what, when." Requestors can be public keys that verify some signed 
request, hashes of objects submitted for proof of permission, etc. In general, there will be 
only one Requestor, typically the public key of some keyholder signing a request or 
authenticating a connection. 


RequestedAuthorization 

The authorization against which the Requestors are being tested in this computation. 
RequestedAuthorizationPeriod 

The time range of an authorization computation. 


BaseAuthorizations 


The group of ACL entries (unsigned certificates) provided as the basis for this computation. 


Credentials 


A group of tuple-certificates used with the BaseAuthorizations to grant authorizations to 


the Requestors. 
Kind of Subject Example Requestor 
Public key (public-key (rsa-pkcs1-shal (e #034) (n #4)) 


Hash of object, key, template, etc. (hash md5 #900150983cd24fb0d6963f7d28e17f72#4 


The most likely Requestor is a public key that signs a request. In common practice there will be one 
Requestor per computation, but it is possible for an ACL or certificate to require multiple signatures or other 
forms of identification before an action is authorized. In that case, there must be multiple Requestors. This 
function can be used in the following modes: 


¢ Toverify the authorization of a specific request, backed up by specific Requestors 


« Tocompute the set of authorizations that a particular set of Requestors has been granted by the 
BaseAuthorizations and Credentials. 


When using this function to verify an authorization, the RequestedAuthorization is the specific 
authorization being requested and the RequestedAut horizationPeriod gives the date and time of that 
request (typically the current date and time) using both NOT_BEFORE and NOT AFTER dates. The result, 
if any, should be an ACL entry with the same authorization that was requested. If such an ACL entry is 
produced by the computation, then the request is authorized. 
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Requested Authorization Example 


(http http://private.cdsa.hp.com/local-data.html ) 


(ftp ftp://private.cdsa.hp.com/users/cme/private/test.txt write) 


Requested Authorization Period Example 


(valid (not-before "1999-07-28_17:00:44") (not-after "1999-07-28_17:00:44") ) 


When using this function to compute the full set of possible authorizations from a set of credentials, rather 
than to verify a specific access request, the inputs should be of the following form: 


* RequestedAuthorizationPeriod is either an empty list or the list "valid", indicating "all time’. 
* RequestedAuthorization is thelist "*", indicating all possible authorizations. 


The result of this computation, if any, will be one or more ACL entries representing all the granted 
authorizations for the indicated requestor. 


The scope of ACLs output from this function is limited to the local system. Each ACL should beinterpreted to 
mean: "for this machine, under these base authorization ACLs and the provided certificates, relative to the 
specified requestors, the following authorizations have been deduced". Those authorizations are available 
only on the current platform (and possibly only for the application providing the ACL) and are therefore in 
the form of an ACL. They are not intended to be used by any other machine or application instance. However, 
the resulting ACLs can be transferred and used outside of the local scope by an entity with authority in the 
target scope/environment. The transfer and use is a three-step process: 


1. Convert the ACL into one or more certificates. The certificates must be signed by some private key with 
appropriate authority in the target scope/environment. 


2. Transfer the certificates to the target environment. 


3. Use the signed certificates as input Credentials to this function in the target scope/environment. 


If the function is successful, check (*AuthorizationResult) ->NumCerts to determine the precise number of 
authorizations granted by this computation. If 0, then the requestors were not authorized. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_AC_INVALID_BASE_ACLS 
CSSMERR_AC_INVALID_ENCODING 

CSSMERR_AC_INVALID_REQUESTOR 
CSSMERR_AC_INVALID_REQUEST_DESCRIPTOR 


CSSMERR_AC_INVALID_TUPLE_CREDENTIALS 


CSSMERR_AC_INVALID_VALIDITY_PERIOD 
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SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Reference Pages 

Functions for the CSSM API: 

CSSM_TP_CertGroupToTupleGroup, CSSM_TP_TupleGroupToCertGroup 
Functions for the AC SPI: 

TP_CertGroupToTupleGroup, TP_TupleGroupToCertGroup 
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NAME 
AC _PassThrough: CSSM_AC PassThrough - Call exported module-specific operations (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_AC_PassThrough 
(CSSM_AC_HANDLE ACHandle, 
CSSM_TP_HANDLE TPHandle, 

CSSM_CL_HANDLE CLHandle, 

CSSM_CC_HANDLE CCHandle, 

const CSSM_DL_DB_LIST *DBList, 

uint32 PassThroughId, 

const void *InputParams, 

void **OutputParams) 


SPI 

CSSM_RETURN CSSMACI AC_PassThrough 
(CSSM_AC_HANDLE ACHandle, 
CSSM_TP_HANDLE TPHandle, 
CSSM_CL_HANDLE CLHandle, 
CSSM_CC_HANDLE CCHandle, 

const CSSM_DL_DB_LIST *DBList, 
uint32 PassThroughId, 

const void *InputParams, 

void **OutputParams) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


ACHandle (input) 


The handle that describes the authorization computation module used to perform this 
function. 


TPHandle (input/optional) 


The handle that describes the trust policy module that can be used by the authorization 
computation service to implement this function. If no trust policy module is specified, the 
AC module uses an assumed TP module, if required. 


CLHand1le (input/optional) 


The handle that describes the add-in certificate library module that can be used to 
manipulate the subject certificate and anchor certificates. If no certificate library module is 
specified, the AC module uses an assumed CL module, if required. 


CCHand1le (input/optional) 
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The handle that describes the cryptographic context containing a handle that describes the 
add-in Cryptographic Service Provider module that can be used to perform cryptographic 
operations as required to perform the requested operation. If no cryptographic context is 
specified, the AC module uses an assumed cryptographic context and CSP module, if 
required. 


DBList (input/optional) 


A list of handle pairs specifying a data storage library module and a data store managed by 
that module. These data stores can contain certificates, CRLs, and policy objects for use by 
the AC module. If noDL and DB handle pairs are specified, the AC module uses an assumed 
DL module and an assumed data store for this operation. 


PassThroughId (input) 
An identifier assigned by the AC module to indicate the exported function to perform. 
InputParams (input) 


A pointer to a module, implementation-specific structure containing parameters to be 
interpreted in a function-specific manner by the requested AC module. If the passthrough 
function requires access to a private key located in the CSP referenced by cSPHandle, then 
InputParams Should contain a passphrase, or a callback or cryptographic context that can 
be used to obtain the passphrase. 


OutputParams (output/optional) 


A pointer toa module, implementation-specific structure containing the output data. The 
service provider will allocate the memory for this structure. The application must free the 
memory for the structure. 


DESCRIPTION 


This function allows applications to call authorization computation module-specific operations that have been 
exported. Such operations might include queries or services specific to the domain represented by the AC 
module. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 

Errors are described in the CDSA Technical Standard. 
CSSMERR_AC_INVALTID_CL_HANDLE 
CSSMERR_AC_ INVALID _CONTEXT_HANDLE 
CSSMERR_AC_INVALID_DBLIST_POINTER 
CSSMERR_AC_ INVALID _DB_ LIST 
CSSMERR_AC_ INVALID DB HANDLE 
CSSMERR_AC_INVALTID_DL_HANDLE 
CSSMERR_AC_INVALID_PASSTHROUGH_ID 
CSSMERR_AC_INVALID_TP_HANDLE 
SEE ALSO 


Inta CDSA Application Devdoper's Guide 
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CL_CertAbortCache 


NAME 
CL_CertAbortCache: CSSM_CL_CertAbortCache - Terminate a certificate cache handle (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 
CSSM_RETURN CSSMAPI CSSM_CL_CertAbortCache 


(CSSM_CL_HANDLE CLHandle, 


CSSM_HANDLE CertHandle) 


SPI¢ 
CSSM_RETURN CSSMAPI CSSM_CL_CertAbortCache 
(CSSM_CL_HANDLE CLHandle, 

CSSM_HANDLE CertHandle) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 
CLHandle (input) 

The handle that describes the certificate library module used to perform this function. 
CertHandle (input) 

The handle that identifies the cached certificate. 


DECRIPTION 


This function terminates a certificate cache handle created and returned by the function 
CSSM_CL_CertCache () (CSSM API) or CL_CertCache () (CL SPI). The Certificate Library module releases all 
cache space and state information associated with the cached certificate. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CL_INVALID_CACHE_HANDLE 


59 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Reference Pages 

Functions for the CSSM API: 
CSSM_CL_CertCache 
Functions for the CLI SPI: 
CL_CertCache 
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CL_CertAbortQuery 


NAME 
CL_CertAbortQuery: CSSM_CL_CertAbortQuery function - Terminate a results handle (CDSA) 


SYNOPSIS 


#include <cssm.h> 


APTI: 
CSSM_RETURN CSSMAPI CSSM_CL_CertAbortQuery 


(CSSM_CL_HANDLE CLHandle, 


CSSM_HANDLE ResultsHandle) 


SPI: 
CSSM_RETURN CSSMAPI CSSM_CL_CertAbortQuery 
(CSSM_CL_HANDLE CLHandle, 
CSSM_HANDLE ResultsHandle) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CLHandle (input) 


The handle that describes the add-in certificate library module used to perform this 
function. 


Result sHandle (input) 


A pointer to the handle that identifies the results of a cSSM_CL_GetFieldValue() (CSSM 
API), of CL_GetFieldValue() (CLI SPI) request. 


DESCRIPTION 


This function terminates a results handle used to access multiple certificate fields identified by a single OID. 
The Result sHandle was created and returned by CSSM_CL_CertGetFirstFieldValue() (CSSM API), or 
CL_CertGetFirstFieldValue() (CL SPI), or CSSM_CL_CertGetFirstCachedFieldValue() (CSSM API), or 
CL_CertGetFirstCachedFieldvValue() (CL SPI). 


The CL releases all intermediate state information associated with the repeating-value query. Once this 
function has been invoked, the results handle is invalid. 


Applications must invoke this function to terminate the Result sHandle. Using 
CSSM_CL_CertGetNextFieldValue() (CSSM API), or CL_CertGetNextFieldvalue() (CL SPI), or 
CSSM_CL_CertGetNextCachedFieldValue() (CSSM API), or CL_CertGetNext CachedFieldValue() (CL 
SPI), to access all of the attributes named by a single OID does not terminate the Result sHandle. 


This function can be invoked to terminate the results handle without accessing all values identified by the 
single OID. 
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RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CL_INVALID_RESULTS_HANDLE 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 


Functions for the CSSM API: 


CSSM_CL_CertGetF irstFiddValue, CSSM_CL_CetGaNextFiddValue, 
CSSM_CL_CertGeF irstCachedFiddValue, CSSM_CL_CatGaNextCachedFiddValue 


Functions for the CLI SPI: 


CL_CetGdFirstFiddValue, CL_CatGaNextFiddValue CL_CatGeFirstCachedFiddValue, 
CL_CetGadNextCachedFiddValue 
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CL_CertCache 


NAME 
CL_CertCache: CSSM_CL_CertCache - Cachea copy of a certificate (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_CL_CertCache 
(CSSM_CL_HANDLE CLHandle, 

const CSSM_DATA *Cert, 
CSSM_HANDLE_PTR CertHandle) 


BSPIs¢ 

CSSM_RETURN CSSMAPI CSSM_CL_CertCache 
(CSSM_CL_HANDLE CLHandle, 

const CSSM_DATA *Cert, 


CSSM_HANDLE_PTR CertHandle) 


LIBRARY 


Common Security Services Manager library (cdsa$Sincssm300_shr.exe) 


PARAMETERS 


CLHandle (input) 

The handle that describes the certificate library module used to perform this function. 
Cert (input) 

A pointer tothe CSSM_DATA structure containing the encoded certificate. 
CertHandle (output) 


A pointer to the CSSM_HANDLE that should be used in all future references to the cached 
certificate. 


DESCRIPTION 


This function caches a copy of a certificate for subsequent accesses using the functions 
CSSM_CL_CertGetFirstCachedFieldValue() (CSSM API), or CL_CertGetFirstCachedFieldValue() (CL 
SPI), and CSSM_CL_CertGetNextCachedFieldValue() (CSSM API), or 
CL_CertGetNextCachedFieldValue() (CL SPI). 


The input certificate must be in an encoded representation. The Certificate Library module can cache the 
certificate in any appropriate internal representation. Parsed or incrementally parsed representations are 
common. The selected representation is opaque to the caller. 


The application must call cSSM_CL_CertAbortCache() (CSSM API), or CL_CertAbortCache() (CL SPI), to 
remove the cached copy when additional get operations will not be performed on the cached certificate. 
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RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CL_INVALID_CERT_POINTER 
CSSMERR_CL_UNKNOWN_FORMAT 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 


Functions for the CSSM API: 


CSSM_CL_CertGeF irstCachedFiddValue, CSSM_ CL _CatGadNexttCachedFiddValue, 
CSSM_CL_CertAbortQuery, CSSM_CL_CertAbortCache 


Functions for the CLI SPI: 


CL_CertGetFirstCachedFiddValue CL_CetGetNextCachedFiddValue CL_CertAbortQuery, 
CL_CertAbortCache 
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CL_CertCreateTemplate 
NAME 


CL_CertCreateTemplate: CSSM_CL_CertCreateTemplate - Allocate and initialize memory for a 
certificate template (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_CL_CertCreateTemplat 
(CSSM_CL_HANDLE CLHandle, 
uint32 NumberOfFields, 
const CSSM_FIELD *CertFields, 
CSSM_DATA_PTR CertTemplate) 
SPI: 
CSSM_RETURN CSSMCLI CL_CertCreateTemplat 
(CSSM_CL_HANDLE CLHandle, 

uint32 NumberOfFields, 
const CSSM_FIELD *CertFields, 
CSSM_DATA_PTR CertTemplate) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CLHandle (input) 

The handle that describes the certificate library module used to perform this function. 
NumberOfFields (input) 

The number of certificate field values specified in the certFields. 
CertFields (input) 


A pointer to an array of OI D/value pairs that identify the field values to initialize a new 
certificate. 


CertTemplate (output) 


A pointer toa CSSM_DATA structure that will contain the unsigned certificate template as 
a result of this function. 


DESCRIPTION 


This function allocates and initializes memory for an encoded certificate template output in 
CertTemplate->Data. The template values are specified by the input Ol D/value pairs contained in 
CertFields. The initialization process includes encoding all certificate field values according to the 
certificate type and certificate encoding supported by the certificate library module. 


The memory for Cert Template->Data is allocated by the service provider using the calling application's 
memory management routines. The application must deallocate the memory. 
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RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CL_INVALID_FIELD_POINTER 
CSSMERR_CL_UNKNOWN_TAG 
CSSMERR_CL_INVALID_NUMBER_OF_FIELDS 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 
CSSM_CL_CetGetAllTemplateFidds, CSSM_CL_CertSign 
Functions for the CLI SPI: 

CL_CertGetAllTemplateFidds, CL_CertSign 
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CL_CertDescribeFormat 


NAME 


CL_CertDescribeFormat: CSSM_CL_CertDescribeFormat - Return a list of the CSSM_OID values 
(CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_CL_CertDescribeFormat 
(CSSM_CL_HANDLE CLHandle, 

uint32 *NumberOfOids, 

CSSM_OID_PTR *OidList) 

SPI: 
CSSM_RETURN CSSMAPI CSSM_CL_CertDescribeFormat 
(CSSM_CL_HANDLE CLHandle, 

uint32 *NumberOfOids, 

CSSM_OID_PTR *OidList) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CLHandle (input) 


The handle that describes the add-in certificate library module used to perform this 
function. 


NumberOfOids (output) 
The length of the returned array of OIDs. 
OidList (output) 


A pointer to the array of CSSM_OIDs that represent the supported certificate format. The 
OID list is allocated by the service provider and must be deallocated by the application. 


DESCRIPTION 


This function returns a list of the CSSM_OID values this certificate library module uses to name and 
reference fields of a certificate Multiple CSSM_OID values can correspond toa single field. These OI Ds can 
be provided as input to CSSM_CL_CertGetFirstFieldValue() (CSSM API), or 
CL_CertGetFirstFieldValue() (CL SPI), to retrieve field values from the certificate The OID also implies 
the data format of the returned value. When multiple OIDs name the same field of a certificate, those Ol Ds 
have different return data formats associated with them. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


67 


ERRORS 
Errors are described in the CDSA Technical Standard. 


None specific to this call. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 

CSSM_CL_CetGetAllFidds, CSSM_CL_CetGeFirstFiddValue CSSM_CL_CetGeFirstCachedFiddValue 
Functions for the CLI SPI: 

CL_CatGdAllFidds, CL_CetGeFirstFiddValue, CL_CetGeFirstCachedFiddValue 
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CL_CertGetAllFields 


NAME 
CL_CertGetAllFields: CSSM_CL_CertGetAllFields - Return a list of input certificate values (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 
CSSM_RETURN CSSMAPI CSSM_CL_CertGetAllFields 
(CSSM_CL_HANDLE CLHandle, 

const CSSM_DATA *Cert, 

uint32 *NumberOfFields, 

CSSM_FIELD_PTR *FieldList) 

SPI: 
CSSM_RETURN CSSMCLI CL_CertGetAllFields 
(CSSM_CL_HANDLE CLHandle, 
const CSSM_DATA *Cert, 
uint32 *NumberOfFields, 


CSSM_FIELD_PTR *FieldList) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CLHandle (input) 


The handle that describes the add-in certificate library module used to perform this 
function. 


Cert (input) 


A pointer tothe CSSM_DATA structure containing the certificate whose fields will be 
returned. 


NumberOfFields (output) 
The length of the returned array of fields. 
FieldList (output) 


A pointer to an array of CSSM_FIELD structures that contain the values of all fields of the 
input certificate. The field list is allocated by the service provider and must be deallocated 
by the application by calling CSSM_CL_FreeFields () (CSSM API), or CL_FreeFields () 
(CL SPI). 


DESCRIPTION 


This function returns a list of the values stored in the input certificate. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 
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ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CL_INVALID_CERT_POINTER 
CSSMERR_CL_UNKNOWN_FORMAT 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

For the CSSM API: 

CSSM_CL_CetGeFirstFiddValue, CSSM_CL_CertDescribeFormat, CSSM_CL_FreeFidds 
For theCLI SPI: 

CL_CertGdFirstFiddValue, CL_CerttDescribeFormat, CL_FreeFidds 
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CL_CertGetAllTemplateFields 


NAME 


CL_CertGetAllTemplateF ields: CSSM_CL_CertGetAl|lTemplateF ields - Extract and return values 
stored in CertTemplate (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_CL_CertGetAllTemplateFields 
(CSSM_CL_HANDLE CLHandle, 

const CSSM_DATA *CertTemplate, 

uint32 *NumberOfFields, 

CSSM_FIELD_PTR *CertFields) 

BPE Is 
CSSM_RETURN CSSMCLI CL_CertGetAllTemplateFields 
(CSSM_CL_HANDLE CLHandle, 

const CSSM_DATA *CertTemplate, 

uint32 *NumberOfFields, 

CSSM_FIELD_PTR *CertFields) 


LIBRARY 


Common Security Services Manager library (cdsa$Sincssm300_shr.exe) 


PARAMETERS 


CLHandle (input) 
The handle that describes the certificate library module used to perform this function. 
CertTemplate (input) 


A pointer to the CSSM_DATA structure containing the packed, encoded certificate 
template. 


NumberOfFields (output) 
The length of the output array of fields. 
CertFields (output) 


A pointer to an array of CSSM_FIELD structures which contains the OI Ds and values of the 
fields of the input certificate template. 


DESCRIPTION 


This function extracts and returns a copy of the values stored in the encoded Cert Template. The memory for 
the CertFields output is allocated by the service provider using the calling application's memory 
management routines. The application must deallocate the memory by calling cSSM_CL_FreeFields () 
(CSSM API), or CL_FreeFields() (CL SPI). 


71 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CL_UNKNOWN_FORMAT 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 

CSSM_CL_FreeFidds, CSSM_CL_CertCreatel emplate 
Functions for the CLI SPI: 

CL_FreeFidds, CL_CertCreateTemplate 


72 


CL_CertGetFirstCachedFieldValue 


NAME 


CL_CertGetF irstCachedF ieldValue: CSSM_CL_CertGetF irstCachedF ieldValue - Return values 
from the cached certificate (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_CL_CertGetFirstCachedFieldValue 
(CSSM_CL_HANDLE CLHandle, 

CSSM_HANDLE CertHandle, 

const CSSM_OID *CertField, 

CSSM_HANDLE_PTR ResultsHandle, 

uint32 *NumberOfMatchedFields, 

CSSM_DATA_PTR *FieldValue) 

SPL: 
CSSM_RETURN CSSMAPI CSSM_CL_CertGetFirstCachedFieldValue 
(CSSM_CL_HANDLE CLHandle, 

CSSM_HANDLE CertHandle, 

const CSSM_OID *CertField, 


CSSM_HANDLE_PTR ResultsHandle, 


uint32 *NumberOfMatchedFields, 
CSSM_DATA_PTR *FieldValue) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CLHandle (input) 


The handle that describes the add-in certificate library module used to perform this 
function. 


CertHandle (input) 


A handle identifying a certificate that the application has temporarily cached with the 
Certificate Library module. The referenced certificate is searched for the field value named 
by CertField. 


CertField (input) 
A pointer to an object identifier that identifies the field value to be extracted from the Cert. 
Result sHandle (output) 


A pointer tothe CSSM_HANDLE that should be used to obtain any additional matching 
fields. 


NumberOfMat chedFields (output) 


The total number of fields that match the CcertField OID. This count includes the first 
match, which was returned by this function. 


FieldValue (output) 
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A pointer to the structure containing the value of the requested field. The structure and the 
field at | "(*FieldValue)->Data" are allocated by the service provider. The 
CSSM_CL_FreeFieldvValue () (CSSM API), or CL_FreeFieldValue() (CL SPI), function can 
be used to deallocate Fieldvalue and (*FieldValue) ->Data. 


DESCRIPTION 


This function returns a single structure containing a set of field values from the cached certificate identified 
by CertHandle. The selected fields are designated by the CSSM_OID CertField and returned in the output 
parameter FieldValue. The OID also identifies the data format of the values returned to the caller. If 
multiple Ol Ds designate the same certificate field, then each such OID defines a distinct data format for the 
returned values. The function CSSM_CL_CertDescribeFormat () (CSSM API), or CL_CertDescribeFormat () 
(CL SPI), provides a list of all CSSM_OID values supported by a certificate library module for naming fields 
of a certificate 


The CertField OID can identify a single occurrence of a set of certificate fields, or multiple occurrences of a 
set of certificate fields. If the CertField OlD matches more than one occurrence, this function outputs the 
total number of matches and a Result sHandle to be used as input to 
CSSM_CertGetNextCachedFieldValue() (CSM API), or CertGetNext CachedFieldValue() (CL SPI), to 
retrieve the remaining matches. The first match is returned as the return value of this function. 


This function determines the complete set of matches. The number of matches and the selected field values do 
not change between this function and subsequent calls to cSSM_CL_CertGetNextCachedFieldValue () 
(CSSM API), or CL_CertGetNextCachedFieldValue() (CL SPI). 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CL_INVALID_CACHE_HANDLE 
CSSMERR_CL_UNKNOWN_TAG 
CSSMERR_CL_NO_FTIELD_VALUES 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 


Functions for the CSSM API: 


CSSM_CL_CerttGetNextCachedFiddValue, CSSM_CL_CertAbortCache, CSSM_CL_CertAbortQuery, 
CSSM_CL CetGetAllFidds, CSSM_CL_CertDescribeF ormat, CSSM_CL_FreeFiddValue 


Functions for the CLI SPI: 


CL_CatGaNettCachedFiddValue CL_CertAbortCache, CL_CertAbortQuery, CL_CertGeAllFidds, 
CL_CertDescribeFormat, CL_FreeFiddValue 
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CL_CertGetFirstFieldValue 


NAME 


CL_CertGetFirstFieldValue: CSSM_CL_CertGetFirstFieldValue- Return the value of the 
certificate field (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_CL_CertGetFirstFieldValue 
(CSSM_CL_HANDLE CLHandle, 

const CSSM_DATA *Cert, 

const CSSM_OID *CertField, 

CSSM_HANDLE_PTR ResultsHandle, 

uint32 *NumberOfMatchedFields, 

CSSM_DATA_PTR *Value) 

SPL: 
CSSM_RETURN CSSMCLI CL_CertGetFirstFieldValue 
(CSSM_CL_HANDLE CLHandle, 

const CSSM_DATA *Cert, 

const CSSM_OID *CertField, 

CSSM_HANDLE_PTR ResultsHandle, 

uint32 *NumberOfMatchedFields, 

CSSM_DATA_PTR *Value) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CLHandle (input) 


The handle that describes the add-in certificate library module used to perform this 
function. 


Cert (input) 
A pointer tothe CSSM_DATA structure containing the certificate. 
CertField (input) 


A pointer to an object identifier which identifies the field value to be extracted from the 
Cert. 


Result sHandle (output) 


A pointer tothe CSSM_HANDLE that should be used to obtain any additional matching 
fields. 


NumberOfMat chedFields (output) 


The total number of fields that match the certField OID. This count includes the first 
match, which was returned by this function. 


Value (output) 
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A pointer to the structure containing the value of the requested field. The structure and the 
field at | "(*Value)->Data" are allocated by the service provider. The 
CSSM_CL_FreeFieldValue () (CSSM API) or CL_FreeFieldValue () (CL SPI) function can 
be used to deallocate *value and (*Value) ->Data. 


DESCRIPTION 


This function returns the value of the certificate field designated by the CSSM_OID CertField. The OID also 
identifies the data format for the field value returned to the caller. If multiple O1Ds name the same certificate 
field, then each such OID defines a distinct data format for the returned field value. The function 
CSSM_CL_CertDescribeFormat () (CSSM API), or CL_CertDescribeFormat () (CL SPI), provides a list of all 
CSSM_OID values supported by a certificate library module for naming fields of a certificate. 


If more than one field matches the certField OID, the first matching field will be returned. The number of 
matching fields is an output parameter, as is the Result sHandle to be used to retrieve the remaining 


matching fields. 


The set of matching fields is determined by this function. The number of matching fields and the field values 
do not change between this function and subsequent calls to CSSM_CL_CertGetNextFieldValue() (CSSM 
API), or CL_CertGetNextFieldvalue() (CL SPI). 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 


Errors are described in the CDSA Technical Standard. 


CSSMERR_CL_INVALID_CERT_POINTER 


CSSMERR_CL_UNKNOWN_FORMAT 
CSSMERR_CL_UNKNOWN_TAG 
CSSMERR_CL_NO_FIELD_VALUES 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 


Functions for the CSSM API: 


CSSM_CL_CertGaNextFiddValue CSSM_CL_CertAbortQuery, CSSM_CL_CertGetAllFidd, 
CSSM_CL_FrefFiddValue CSSM CL_CetDescribeormat, CSSM_CL_FreiddValue 


Functions for the CLI SPI: 


CL_CatGaNextFiddValue, CL_CertAbortQuery, CL_CetGetAllFidd, CL_FreeFiddValue 
CL_CertDescribeFormat, CL_FreeFiddValue 
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CL_CertGetKeylI nfo 


NAME 


CL_CertGetK eyl nfo: CSSM_CL_CertGetK eyI nfo - Return the public key and integral information 
(CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_CL_CertGetKeyInfo 
(CSSM_CL_HANDLE CLHandle, 

const CSSM_DATA *Cert, 

CSSM_KEY_PTR *Key) 

SPI: 
CSSM_RETURN CSSMCLI CL_CertGetKeyInfo 
(CSSM_CL_HANDLE CLHandle, 
const CSSM_DATA *Cert, 
CSSM_KEY_PTR *Key) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CLHandle (input) 


The handle that describes the add-in certificate library module used to perform this 
function. 


Cert (input) 


A pointer to the CSSM_DATA structure containing the certificate from which to extract the 
public key information. 


Key (output) 


A pointer tothe CSSM_KEY structure containing the public key and possibly other key 
information. The CSSM_KEY structure and its substructures are allocated by the service 
provider and must be deallocated by the application. 


DESCRIPTION 


This function returns the public key and integral information about the key from the specified certificate. The 
key structure returned is a compound object. It can be used in any function requiring a key, such as creatinga 
cryptographic context. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 
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ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CL_INVALID_CERT_POINTER 
CSSMERR_CL_UNKNOWN_FORMAT 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 
CSSM_CL_CetGeFirstFiddValue, CSSM_CL_FreeFiddValue 
Functions for the CLI SPI: 

CL_CertGdFirstFiddValue CL_FreeFiddValue 
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CL _CertGetNextCachedFieldValue 
NAME 
CSSM_CL_CertGetNextCachedFieldValue - Return the value of a certificate field (CDSA) 


SYNOPSIS 


#include <cssm.h> 


APTI: 
CSSM_RETURN CSSMAPI CSSM_CL_CertGetNextCachedFieldValu 


(CSSM_CL_HANDLE CLHandle, 
CSSM_HANDLE ResultsHandle, 
CSSM_DATA_PTR *FieldValue) 
SPI: 
CSSM_RETURN CSSMAPI CSSM_CL_CertGetNextCachedFieldValu 
(CSSM_CL_HANDLE CLHandle, 
CSSM_HANDLE ResultsHandle, 
CSSM_DATA_PTR *FieldValue) 


LIBRARY 


Common Security Services Manager library (cdsa$Sincssm300_shr.exe) 


PARAMETERS 


CLHandle (input) 

The handle that describes the certificate library module used to perform this function. 
Result sHandle (input) 

The handle that identifies the results of a certificate query. 
FieldValue (output) 


A pointer to the structure containing the value of the requested field. The structure and the 
field at | "(*FieldValue)->Data" are allocated by the service provider. The 
CSSM_CL_FreeFieldValue() (CSSM API), or CL_FreeFieldValue() (CL SPI) function can 
be used to deallocate *FieldValue and (*FieldValue) ->Data. 


DESCRIPTION 


This function returns the value of a certificate field, when that field occurs multiple times in a certificate. 
Certificates with repeated fields (such as multiple signatures) have multiple field values corresponding toa 
single OID. A call to the function cSSM_CL_CertGetFirstCachedFieldvalue () (CSSM API), or 
CL_CertGetFirstCachedFieldvalue() (CL SPI), returns a Result sHandle identifying the size and values 
contained in the result set. The CSSM_CL_CertGetNextCachedFieldValue() (CSSMAPI), or 
CL_CertGetNextCachedFieldValue () (CL SPI), function can be called repeatedly to obtain these values, one 
at a time The result set does not change in size or value between calls to this function. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 
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ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CL_INVALID_RESULTS_HANDLE 
CSSMERR_CL_NO_FIELD_VALUES 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 


Functions for the CSSM API: 


CSSM_CL_CertGeF irstCachedFiddValue, CSSM_CL_CertAbortCache, CSSM_CL_CertAbortQuey, 
CSSM_CL_CetGetAllFidds, CSSM_CL_CetDescribeFormat, CSSM_CL_FreeFiddValue 


Functions for the CLI SPI: 


CL_CertGeFirstCachedFiddValue CL_CertAbortCache CL_CertAbortQuery, CL_CertGetAllFidds, 
CL_CertDescribeFormat, CL_FreeiddValue 
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CL_CertGetNextFieldValue 


NAME 


CL_CertGetNextFieldValue: CSSM_CL_CertGetN extFieldValue - Return the value of a certificate 
field (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_CL_CertGetNextFieldValu 
(CSSM_CL_HANDLE CLHandle, 

CSSM_HANDLE ResultsHandle, 

CSSM_DATA_PTR *Value) 

SPI: 
CSSM_RETURN CSSMCLI CL_CertGetNextFieldValu 
(CSSM_CL_HANDLE CLHandle, 

CSSM_HANDLE ResultsHandle, 

CSSM_DATA_PTR *Value) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CLHandle (input) 


The handle that describes the add-in certificate library module used to perform this 
function. 


Result sHandle (input) 
The handle that identifies the results of a certificate query. 
Value (output) 


A pointer to the structure containing the value of the requested field. The structure and the 
field at | "(*Value)->Data" are allocated by the service provider. The 
CSSM_CL_FreeFieldValue() (CSSM API) or CL_FreeFieldvalue () (CL SPI), function can 
be used to deallocate *value and (*Value) ->Data. 


DESCRIPTION 


This function returns the value of a certificate field, when that field occurs multiple times in a certificate. 
Certificates with repeated fields (such as multiple signatures) have multiple field values corresponding toa 
single OID. A call to the function cSSM_CL_CertGetFirstFieldValue() (CSSM API), or 
CL_CertGetFirstFieldValue() (CL SPI), returns a results handle identifying the size and values contained 
in the result set. The cCSSM_CL_CertGetNextFieldValue() (CSSM API), or CL_CertGetNextFieldValue () 
(CL SPI), function can be called repeatedly to obtain these values, one at a time. The result set does not 
change in size or value between calls to this function. 
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RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CL_INVALID_RESULTS_HANDLE 
CSSMERR_CL_NO_FTELD_VALUES 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 

CSSM_CL_CertGeFirstFiddValue, CSSM_CL_CertAbortQuery, CSSM_CL_FreeFiddValue 
Functions for the CLI SPI: 

CL_CertGdFirstFiddValue, CL_CertAbortQuery, CL_FreFiddValue 
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CL_CertGroupFromVerifiedB undle 


NAME 


CL_CertGroupF romVerifiedBundle: CSSM_CL_CertGroupF romVerifiedBundle - Verify the 
signature of a bundle (CDSA) 


SYNOPSIS 


#include <cssm.h> 


APTI: 

CSSM_RETURN CSSMAPI CSSM_CL_CertGroupFromVerifiedBundle 
(CSSM_CL_HANDLE CLHandle, 
CSSM_CC_HANDLE CCHandle, 

const CSSM_CERT_BUNDLE *CertBundle, 
const CSSM_DATA *SignerCert, 


CSSM_CERTGROUP_PTR *CertGroup) 


CSSM_RETURN CSSMCLI CL_CertGroupFromVerifiedBundle 
(CSSM_CL_HANDLE CLHandle, 

CSSM_CC_HANDLE CCHandle, 

const CSSM_CERT_BUNDLE *CertBundle, 

const CSSM_DATA *SignerCert, 

CSSM_CERTGROUP_PTR *CertGroup) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CLHandle (input) 


The handle that describes the add-in certificate library module used to perform this 
function. 


CCHand1le (input/optional) 
The handle of the cryptographic context to control the verification operation. 
CertBundle (input) 


A structure containing a reference to a signed, encoded bundle of certificates and to 
descriptors of the type and encoding of the bundle. The bundled certificates are to be 
separated into a certificate group (list of individual encoded certificates). If the bundle type 
and bundle encoding are not specified, the add-in module might either attempt to decode the 
bundle assuming a default type and encoding or might immediately fail. 


SignerCert (input/optional) 


The certificate to be used to verify the signature on the certificate bundle. If the bundle is 
signed but this field is not specified, then the module will assume a default certificate for 
verification. 


CertGroup (output) 
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A pointer to the certificate group, represented as an array of individual, encoded 
certificates. The certificate group and CSSM_CERTGROUP substructures are allocated by 
the serivce provider and must be deallocated by the application. The group contains all 
certificates contained in the certificate bundle. 


DESCRIPTION 


This function accepts as input a certificate bundle (a codified and signed aggregation of the certificates in the 
group), verifies the signature of the bundle (if a signature is present), and returns a certificate group (as an 
array of individual certificates) including every certificate contained in the bundle. The signature on the 
certificate aggregate is verified using the cryptographic context and possibly using the input signer 
certificate. The CL module embeds the knowledge of the verification scope for the bundle types that it 
supports. A CL module's supported bundle types and encodings are available to applications by querying the 
CSSM registry. The type and encoding of the certificate bundle must be specified with the input bundle. If 
signature verification is successful, the certificate aggregate will be parsed into a certificate group whose 
order corresponds to the certificate aggregate ordering. This certificate group will then be returned to the 
calling application. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CL_INVALID_CONTEXT_HANDLE 
CSSMERR_CL_INVALID_BUNDLE_POINTER 
CSSMERR_CL_INVALID_BUNDLE_INFO 
CSSMERR_CL_INVALID_CERT_POINTER 
CSSMERR_CL_INVALID_CERTGROUP_POINTER 
CSSMERR_CL_UNKNOWN_FORMAT 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 
CSSM_CL_CertGroupToSignedBundle 
Functions for the CLI SPI: 
CL_CertGroupToSignedBundle 
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CL_CertGroupToSignedBundle 
NAME 


CL_CertGroupToSignedBundle: CSSM_CL_CertGroupToSignedBundle - Convert a certificate 
group toa certificate bundle (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_CL_CertGroupToSignedBundle 

(CSSM_CL_HANDLE CLHandle, 

CSSM_CC_HANDLE CCHandle, 

const CSSM_CERTGROUP *CertGroupToBundle, 

const CSSM_CERT_BUNDLE_HEADER *BundleInfo, 

CSSM_DATA_PTR SignedBundle) 

SPI: 

CSSM_RETURN CSSMCLI CL_CertGroupToSignedBundle 

(CSSM_CL_HANDLE CLHandle, 

CSSM_CC_HANDLE CCHandle, 

const CSSM_CERTGROUP *CertGroupToBundle, 

const CSSM_CERT_BUNDLE_HEADER *BundleInfo, 
R 


CSSM_DATA_PTR SignedBundle) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CLHandle (input) 


The handle that describes the add-in certificate library module used to perform this 
function. 


CCHand1le (input/optional) 


The handle of the cryptographic context to control the signing operation. The operation will 
fail if a signature is required for this type of bundle and the cryptographic context is not 
valid. 


CertGroupToBundle (input) 


An array of individual, encoded certificates. All certificates in this list will be included in the 
resulting certificate bundle. 


BundleInfo (input/optional) 


A structure containing the type and encoding of the bundle to be created. If the type and the 
encoding are not specified, then the module will use a default bundle type and bundle 
encoding. 


SignedBundle (output) 
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The function returns a pointer toa signed certificate bundle containing all certificates in the 
certificate group. The bundle is of the type and encoding requested by the caller or is the 
default type defined by the library module if the BundleInfo was not specified by the caller. 
The SignedBundle->Data is allocated by the service provider and must be deallocated by 
the application. 


DESCRIPTION 


This function accepts as input a certificate group (as an array of individual certificates) and returnsa 
certificate bundle (a codified and signed aggregation of the certificates in the group). The certificate group will 
first be encoded according to the BundleInfo input by the user. If BundleInfo is NULL, the library will 
perform a default encoding for its default bundle type. If possible, the certificate group ordering will be 
maintained in this certificate aggregate encoding. After encoding, the certificate aggregate will be signed 
using the input context. The CL module embeds knowledge of the signing scope for the bundle types it 
supports. The signature is then associated with the certificate aggregate according to the bundle type and 
encoding rules and is returned as a bundle to the calling application. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CL_INVALID_CONTEXT_HANDLE 
CSSMERR_CL_INVALID_CERTGROUP_POINTER 
CSSMERR_CL_INVALID_CERT_POINTER 
CSSMERR_CL_UNKNOWN_FORMAT 
CSSMERR_CL_INVALID_BUNDLE_POINTER 
CSSMERR_CL_INVALID_BUNDLE_INFO 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 
CSSM_CL_CertGroupFromVerifiedBundle 
Functions for the CLI SPI: 
CL_CertGroupFromVerifiedBundle 


86 


CL_CertSign 


NAME 
CSSM_CL_CertSign - Sign a certificate (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_CL_CertSign 
(CSSM_CL_HANDLE CLHandle, 
CSSM_CC_HANDLE CCHandle, 

const CSSM_DATA *CertTemplate, 

const CSSM_FIELD *SignScope, 

uint32 ScopeSize, 

CSSM_DATA_PTR SignedCert) 

SPI: 
CSSM_RETURN CSSMCLI CL_CertSign 
(CSSM_CL_HANDLE CLHandle, 
CSSM_CC_HANDLE CCHandle, 

const CSSM_DATA *CertTemplate, 
const CSSM_FIELD *SignScope, 
uint32 ScopeSize, 

CSSM_DATA_PTR SignedCert) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CLHandle (input) 


The handle that describes the add-in certificate library module used to perform this 
function. 


CCHandle (input) 


A signature context defining the CSP, signing algorithm, and private key that must be used 
to perform the operation. The passphrase for the private key is also provided. 


CertTemplate (input) 


A pointer toa CSSM_DATA structure containing a certificate template in the default 
format supported by this CL. The template contains values that are currently contained in 
or will be contained in a signed certificate. 


SignScope (input/optional) 


A pointer tothe CSSM_FIELD array containing the Ol D/value pairs of the fields to be 
signed. A null input signs all the fields provided by CertTemplate. 


ScopeSize (input) 


The number of entries in the SignScope list. If the sign scope is not specified, the input 
value for scope size must be zero. 


SignedCert (output) 
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A pointer tothe CSSM_DATA structure containing the signed certificate. 


DESCRIPTION 


This function signs a certificate using the private key and signing algorithm specified in the ccHandle. The 
result is a signed, encoded certificate in Signedcert. The certificate field values are specified in the input 
certificate template. The template is constructed using CSSM_CL_CertCreateTemplate() (CSSM API), or 
CL_CertCreateTemplate () (CL SPI). The template is in the default format for this CL. 


The cCHandle must be a signature context created using the function 

CSSM_CSP_CreateSignatureContext () (CSSM API), or CSP_CreateSignatureContext () (SPI). The context 
must specify the Cryptographic Services Provider (CSP) module, the signing algorithm, and the signing key 
that must be used to perform this operation. The context must also provide the passphrase or a callback 
function to obtain the passphrase required to access and use the private key. 


The fields included in the signing operation are identified by the OI Ds in the optional SignScope array. 


The memory for the SignedCert->Data output is allocated by the service provider using the calling 
application's memory management routines. The application must deallocate the memory. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CL_INVALID_CONTEXT_HANDLE 
CSSMERR_CL_UNKNOWN_FORMAT 
CSSMERR_CL_INVALID_FIELD_POINTER 
CSSMERR_CL_UNKNOWN_TAG 
CSSMERR_CL_INVALID_SCOPE 
CSSMERR_CL_INVALID_NUMBER_OF_FIELDS 
CSSMERR_CL_SCOPE_NOT_SUPPORTED 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 

CSSM_CL_CertVerify, CSSM_CL_CertCreatelemplate 
Functions for the CLI SPI: 

CL_CertVerify, CL_CertCreateTemplate 


88 


CL_CertVerify 


NAME 
CL_CertVerify: CSSM_CL_CertVerify - Verify a signed certificate (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_CL_CertVerify 
(CSSM_CL_HANDLE CLHandle, 
CSSM_CC_HANDLE CCHandle, 

const CSSM_DATA *CertToBeVerified, 
const CSSM_DATA *SignerCert, 

const CSSM_FIELD *VerifyScope, 

uint32 ScopeSize) 

SPI: 
CSSM_RETURN CSSMAPI CSSM_CL_CertVerify 
(CSSM_CL_HANDLE CLHandle, 
CSSM_CC_HANDLE CCHandle, 

const CSSM_DATA *CertToBeVerified, 
const CSSM_DATA *SignerCert, 

const CSSM_FIELD *VerifyScope, 

uint32 ScopeSize) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CLHandle (input) 


The handle that describes the add-in certificate library module used to perform this 
function. 


CCHand1e (input/optional) 
The handle that describes the context of this cryptographic operation. 


Cert ToBeVerified (input) 


A pointer tothe CSSM_DATA structure with a certificate containing at least one signature 
for verification. An unsigned certificate template cannot be verified. 


SignerCert (input/optional) 


A pointer tothe CSSM_DATA structure containing the certificate used to sign the subject 
certificate. This certificate provides the public key to use in the verification process and if 
the certificate being verified contains multiple signatures, the signer's certificate indicates 
which signature is to be verified. 


VerifyScope (input/optional) 
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A pointer tothe CSSM_FIELD array containing the tag/value pairs of the fields to be used 
in verifying the signature. (This should include all fields that were used to calculate the 
signature) If the verify scope is null, the certificate library module assumes that its default 
set of certificate fields were used to calculate the signature, and those same fields are used 
in the verification process. 


ScopeSize (input) 


The number of entries in the verify scope list. If the verification scope is not specified, the 
input value for scope size must be zero. 


DESCRIPTION 


This function verifies that the signed certificate has not been altered since it was signed by the designated 
signer. Only one signature is verified by this function. If the certificate to be verified includes multiple 
signatures, this function must be applied once for each signature to be verified. This function verifies a digital 
signature over the certificate fields specified by VerifyScope. If the verification scope fields are not specified, 
the function performs verification using a preselected set of fields in the certificate. 


The caller can specify a Cryptographic Service Provider (CSP) and verification algorithm that the CL can use 
to perform the verification. The handle for the CSP is contained in the cryptographic context identified by 
CCHandle. 


The verification process requires that the caller must specify the necessary verification algorithm 
parameters. These parameter values are specified in one of two locations: 


« Asafield valuein the SignerCert parameter 
¢ Asaset of algorithm parameters contained in the cryptographic context identified by ccHandle 


If both of the preceding arguments are supplied, a consistency check is performed to ensure that they result 
in the same verification algorithm parameters. If they are not consistent, an error is returned. If only one of 
the above arguments is supplied, that argument is used to generate the verification algorithm parameters. If 
no algorithm parameters are found, the certificate cannot be verified and the operation fails. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 

Errors are described in the CDSA Technical Standard. 
CSSMERR_CL_INVALID_CONTEXT_HANDLE 
CSSMERR_CL_INVALID_CERT_POINTER 
CSSMERR_CL_UNKNOWN_FORMAT 
CSSMERR_CL_INVALID_ FIELD POINTER 
CSSMERR_CL_UNKNOWN_TAG 
CSSMERR_CL_INVALID_SCOPE 
CSSMERR_CL_INVALID_NUMBER_OF_FIELDS 
CSSMERR_CL_SCOPE_NOT_SUPPORTED 
CSSMERR_CL_VERIFICATION_ FATLURE 
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SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 
CSSM_CL_CetSign 
Functions for the CLI SPI: 
CL_CertSign 
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CL_CertVerifyWithKey 
NAME 
CL_CertVerifyWithK ey: CSSM_CL_CertVerifyWithK ey - Verify with a key (CDSA) 


SYNOPSIS 


# include <cssm.h> 


API: 


CSSM_RETURN CSSMAPI CSSM_CL_CertVerifyWithKey 
(CSSM_CL_HANDLE CLHandle, 

CSSM_CC_HANDLE CCHandle, 

const CSSM_DATA *CertToBeVerified) 


SPI: 


CSSM_RETURN CSSMCLI CL_CertVerifyWithKey 
(CSSM_CL_HANDLE CLHandle, 

CSSM_CC_HANDLE CCHandle, 

const CSSM_DATA *CertToBeVerified) 


LIBRARY 


Common Security Services Manager library (cdsa$Sincssm300_shr.exe) 


PARAMETERS 


CLHandle (input) 


The handle that describes the certificate library service module used to perform this 
function. 


CCHandle (input) 


A signature verification context defining the CSP, verification algorithm, and public key 
that must be used to perform the operation. 


Cert ToBeVerified (input) 


A signed certificate whose signature is to be verified. 


DESCRIPTION 


This function verifies that the cert ToBeVerified parameter was signed using a specific private key and that 
the certificate has not been altered since it was signed using that private key. The public key corresponding to 
the private signing key is used in the verification process. 


The CCHandle, must be a signature verification context created using the function 
CSSM_CSP_CreateSignatureContext () (CSSM API), or cSP_CreateSignatureContext () (SPI). The context 
must specify the Cryptographic Services Provider (CSP) module, the verification algorithm, and the public 
verification key that must be used to perform this operation. 
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RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 


indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CL_INVALID_CONTEXT_HANDLE 
CSSMERR_CL_INVALID_CERT_POINTER 
CSSMERR_CL_UNKNOWN_FORMAT 

CSSMERR_CL_VERIFICATION_FAILURE 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 
CSSM_CL_CertVerify, CSSM_CL_CrlVerify 
Functions for the CLI SPI: 

CL_CertVerify, CL_CrlVerify 
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CL_CrlAbortCache 


NAME 
CL_CrlAbortCache: CSSM_CL_CrlAbortCache - Terminate a CRL cache handle (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_CL_CrlAbortCache 
(CSSM_CL_HANDLE CLHandle, 

CSSM_HANDLE CrlHandle) 

SPI: 
CSSM_RETURN CSSMCLI CL_CrlAbortCache 
(CSSM_CL_HANDLE CLHandle, 
CSSM_HANDLE CrlHandle) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 
CLHandle (input) 

The handle that describes the certificate library module used to perform this function. 
CrlHandle (input) 

The handle that identifies the cached CRL. 


DESCRIPTION 


This function terminates a CRL cache handle created and returned by the function CSSM_CL_Cr1Cache () 
(CSSM API), or CL_Cricache() (CL SPI). The Certificate Library module releases all cache space and state 
information associated with the cached CRL. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CL_INVALID_CACHE_HANDLE 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 
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Online Help 


Functions for the CSSM API: 


CSSM_CL_CrlCache 
Functions for the CLI SPI: 
CL_CrlCache 
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CL_CrlAbortQuery 


NAME 
CL_CrlAbortQuery: CSSM_CL_CrlAbortQuery - Terminate a query (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_CL_CrlAbortQuery 
(CSSM_CL_HANDLE CLHandle, 

CSSM_HANDLE ResultsHandle) 

SPI: 
CSSM_RETURN CSSMCLI CL_CrlAbortQuery 
(CSSM_CL_HANDLE CLHandle, 
CSSM_HANDLE ResultsHandle) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CLHandle (input) 


The handle that describes the add-in certificate library module used to perform this 
function. 


Result sHandle (input) 


The handle that identifies the results of a CRL query. 


DESCRIPTION 


This function terminates the query initiated by cSSM_CL_CrlGetFirstFieldValue() or 
CSSM_CL_CrlGetFirstCachedFieldValue() function (or their CL SPI equivalents), and allows the CL to 
release all intermediate state information associated with the repeating-value get operation. Once this 
function has been invoked, the results handle is invalid. 


Applications must invoke this function to terminate the Result sHandle. Using 
CSSM_CL_CrlGetNextFieldValue() of CSSM_CL_CrlGetNextCachedFieldValue() (or their CL SPI 
equivalents), to access all of the attributes named by a single OID does not terminate the Result sHandle. 
This function can be invoked to terminate the results handle without accessing all of the values identified by 
the single OID. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 
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CSSMERR_CL_INVALID_RESULTS_HANDLE 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 


Functions for the CSSM API: 


CSSM_CL_CrlGetFirstFiddValue CSSM_CL_CrilG&NextFiddValue, 
CSSM_CL_CrlGe@FirstCachedFiddValue, CSSM_CL_CriGeNexttCachedF iddValue 


Functions for the CL SPI: 


CL_CriGetFirstFiddValue CL_CriGea&NextFiddValue, CL_CrlGetFirstCachedFiddValue, 
CL_CrlGetNextCachedF iddValue 
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CL_CriAddCert 


NAME 
CL_CrlAddCert: CSSM_CL_CrlAddCert - Revoke an input certificate (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 
CSSM_RETURN CSSMAPI CSSM_CL_CrlAddCert 
(CSSM_CL_HANDLE CLHandle, 
CSSM_CC_HANDLE CCHandle, 

const CSSM_DATA *Cert, 

uint32 NumberOfFields, 

const CSSM_FIELD *CrlEntryFields, 
const CSSM_DATA *OldCrl, 

CSSM_DATA_PTR NewCr1) 

SPI: 
CSSM_RETURN CSSMCLI CL_CrlAddCert 
(CSSM_CL_HANDLE CLHandle, 
CSSM_CC_HANDLE CCHandle, 

const CSSM_DATA *Cert, 

uint32 NumberOfFields, 

const CSSM_FIELD *CrlEntryFields, 
const CSSM_DATA *OldCrl, 
CSSM_DATA_PTR NewCr1) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CLHandle (input) 


The handle that describes the add-in certificate library module used to perform this 
function. 


CCHandle (input) 
The handle that describes the context of this cryptographic operation. 
Cert (input) 
A pointer tothe CSSM_DATA structure containing the certificate to be revoked. 
NumberOfFields (input) 
The number of Ol D/value pairs specified in the CrlEntryFields input parameter. 


po 


Cr 


Ent ryFields (input) 


An array of OI D/value pairs specifying the initial values for descriptive data fields of the 
new CRL entry. 


OldCrl (input) 
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A pointer tothe CSSM_DATA structure containing the CRL to which the newly revoked 
certificate will be added. 


NewCr1 (output) 


A pointer to the CSSM_DATA structure containing the updated CRL. The NewCr1->Data is 
allocated by the service provider and must be deallocated by the application. 


DESCRIPTION 


This function revokes the input certificate by adding a record representing the certificate to the CRL. The 
values for the new entry in the CRL are specified by the list of Ol D/value input pairs. The reason for 
revocation is a typical value specified in the list. The new CRL entry is signed using the private key and 
signing algorithm specified in the ccHandle. 


The ccHandle must be a context created using the function CSSM_CSP_CreateSignatureContext () (CSSM 
API), or CSP_CreateSignatureContext () (CL SPI). The context must specify the Cryptographic Services 
Provider (CSP) module, the signing algorithm, and the signing key that must be used to perform this 
operation. The context must also provide the passphrase or a callback function to obtain the passphrase 
required to access and use the private key. 


The operation is valid only if the CRL has not been closed by the process of signing the CRL, by calling 
CSSM_CL_Cr1Sign() (CSSM API), or CL_Cr1Sign() (CL SPI). Once the CRL has been signed, entries cannot 
be added or removed. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 

Errors are described in the CDSA Technical Standard. 
CSSMERR_CL_INVALID_CONTEXT_HANDLE 
CSSMERR_CL_INVALID_CERT_POINTER 
CSSMERR_CL_UNKNOWN_FORMAT 
CSSMERR_CL_INVALID_ FIELD POINTER 
CSSMERR_CL_UNKNOWN_TAG 
CSSMERR_CL_INVALID_NUMBER_OF_FIELDS 
CSSMERR_CL_INVALID_CRL_ POINTER 
CSSMERR_CL_CRL_ALREADY_SIGNED 

SEE ALSO 

Books 


Inta CDSA Application Devdoper's Guide 


Online Help 


Functions for the CSSM API: 
CSSM_CL_CrlRenoveCet 
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Functions for the CLI SPI: 
CL_CrlRenoveCert 
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CL_CriCache 


NAME 
CL_CrilCache: CSSM_CL_CrlCache- Cachea copy of a certificate revocation list (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_CL_CrlCache 
(CSSM_CL_HANDLE CLHandle, 

const CSSM_DATA *Crl, 

CSSM_HANDLE PTR CrlHandle) 


SPI: 

CSSM_RETURN CSSMCLI CL_CrilCache 
(CSSM_CL_HANDLE CLHandle, 

const CSSM_DATA *Crl, 


CSSM_HANDLE_PTR CrlHandle) 


LIBRARY 


Common Security Services Manager library (cdsa$Sincssm300_shr.exe) 


PARAMETERS 


CLHandle (input) 
The handle that describes the certificate library module used to perform this function. 
Crl (input) 
A pointer tothe CSSM_DATA structure containing the encoded CRL. 
CrlHandle (output) 


A pointer to the CSSM_HANDLE that should be used in all future references to the cached 
CRL. 


DESCRIPTION 


This function caches a copy of a CertificateRevocationList (CRL) for subsequent accesses using the 
functions CSSM_CL_Cr1GetFirstFieldValue() and CSSM_CL_CrlGetNextFieldValue() (or their CL SPI 
equivalents). 


Theinput CRL must bein an encoded representation. The Certificate Library module can cache the CRL in 
any appropriate internal representation. Parsed or incrementally parsed representations are common. The 
selected representation is opaque to the caller. 


The application must call cSSM_CL_CrlCacheAbort () (CSSM API), or CL_Cr1lCacheAbort () (CL SPI), to 
remove the cached copy when additional get operations will not be performed on the cached CRL. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 
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ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CL_INVALID_CRL_POINTER 
CSSMERR_CL_UNKNOWN_FORMAT 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 


Functions for the CSSM API: 


CSSM_CL_CrlGetFirstCachedFiddValue, CSSM_CL_CriGetNextCachedFiddValue 
CSSM_CL_IsCetlnCachedCrl, CSSM_CL_CrlAbortQuery, CSSM_CL_CrlAbortCache 


Functions for the CLI SPI: 


CL_CrlGetFirstCachedFiddValue CL_CriGa&NextCachedFiddValue, CL_IsCertInCachedCrl, 
CL_CrlAbortQuery, CL_CrlAbortCache 
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CL_CriCreateTemplate 
NAME 


CL_CrilCreateTemplate: CSSM_CL_CrlCreateTemplate - Create an unsigned, memory-resident 
CRL (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_CL_CrlCreateTemplate 
(CSSM_CL_HANDLE CLHandle, 

uint32 NumberOfFields, 

const CSSM_FIELD *CrlTemplate, 

CSSM_DATA_PTR NewCr1) 

SPI: 
CSSM_RETURN CSSMCLI CL_CrlCreateTemplate 
(CSSM_CL_HANDLE CLHandle, 

uint32 NumberOfFields, 

const CSSM_FIELD *CrlTemplate, 
CSSM_DATA_PTR NewCr1) 


LIBRARY 


Common Security Services Manager library (cdsa$Sincssm300_shr.exe) 


PARAMETERS 


CLHandle (input) 


The handle that describes the add-in Certificate Library module used to perform this 
function. 


NumberOfFields (input) 
The number of O1 D/value pairs specified in the CrilTemplate input parameter. 
CrlTemplate (input) 


An array of OI D/value pairs specifying the initial values for descriptive data fields of the 
new CRL. 


NewCrl (output) 


A pointer to the CSSM_DATA structure containing the new CRL. The NewCrl-> Data is 
allocated by the service provider and must be deallocated by the application. 


DESCRIPTION 


This function creates an unsigned, memory-resident CRL. Fields in the CRL are initialized with the 
descriptive data specified by the Ol D/value input pairs. The specified OI D/value pairs can initialize all or a 
subset of the general attribute fields in the new CRL. Subsequent values can be set using the 
CSSM_CL_CrlSetFields() (CSSM API) or the cL_crlSetFields () (CL SPI) function. Thenew CRL contains 
no revocation records. 
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RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CL_INVALID_FIELD_POINTER 
CSSMERR_CL_UNKNOWN_TAG 
CSSMERR_CL_INVALID_NUMBER_OF_FIELDS 
CSSMERR_CL_INVALID_CRL_POINTER 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 

CSSM_CL_CrlSeFidds, CSSM_CL_CrlAddCert, CSSM_CL_CrlSign, CSSM_CL_CertGetF irstFiddValue 
Functions for the CLI SPI: 

CL_CriSe@Fidds, CL_CrlAddCet, CL_CrlSign, CL_CetGetF irstFiddValue 
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CL_CriDescribeFormat 


NAME 


CL_CrlDescribeFormat: CSSM_CL_CrlDescribeFormat - Return a list of the CSSM_OID values 
(CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_CL_CrlDescribeFormat 
(CSSM_CL_HANDLE CLHandle, 

uint32 *NumberOfOids, 

CSSM_OID_PTR *OidList) 

SPI: 
CSSM_RETURN CSSMCLI CL_CrlDescribeFormat 
(CSSM_CL_HANDLE CLHandle, 

uint32 *NumberOfOid, 

CSSM_OID_PTR *OidList) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CLHandle (input) 


The handle that describes the add-in certificate library module used to perform this 
function. 


NumberOfOids (output) 
The length of the returned array of OIDs. 
OidList (output) 


A pointer to the array of CSSM_OIDs that represent the supported CRL format. The OID 
list is allocated by the service provider and must be deallocated by the application. 


DESCRIPTION 


This function returns a list of the CSSM_OID values the Certificate Library module uses to name and 
reference fields of aCRL. Multiple CSSM_OID values can correspond to a single field. These OIDs can be 
provided as input tocCSSM_CL_CrlGetFirstFieldvalue() (CSSM API), or CL_CriGetFirstFieldValue () 
(CL SPI), calls to retrieve field values from the CRL. The OID also implies the data format of the returned 
value. When multiple O1Ds name the same field of a CRL, those OI Ds have different return data formats 
associated with them. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 
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ERRORS 
Errors are described in the CDSA Technical Standard. 


None specific to this call. 


SEE ALSO 
Inta CDSA Application Devdoper's Guide 


106 


CL_CriGetAlliCachedRecordFields 


NAME 


CL_CrlGetAllCachedR ecordFields: CSSM_CL_CrlGetAllCachedRecordFields - Return field values 
from a CRL record (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_CL_CrlGetAllCachedRecordFields 
(CSSM_CL_HANDLE CLHandle, 

CSSM_HANDLE CrlHandle, 

const CSSM_DATA *CrlRecordIndex, 

uint32 *NumberOfFields, 

CSSM_FIELD_PTR *Fields) 


CSSM_RETURN CSSMCLI CL_CrlGetAllCachedRecordFields 
(CSSM_CL_HANDLE CLHandle, 

CSSM_HANDLE CrlHandle, 

const CSSM_DATA *CrlRecordIndex, 

uint32 *NumberOfFields, 

CSSM_FIELD_PTR *Fields) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CLHandle (input) 


The handle that describes the add-in certificate library module used to perform this 
function. 


CrlHandle (input) 


A handle identifying a CRL that the application has temporarily cached with the Certificate 
Library module. The referenced CRL must contain the CRL record identified by 
CrlRecordindex. 


CrlRecordIndex (input) 

An index value identifying a particular revocation record in a cached CRL. 
NumberOfFields (output) 

The number of OI D-value pairs returned by this function. 
Fields (output) 


A pointer to an array of CSSM_FIELD structures, describing the contents of the preselected 
CRL record using Ol D-value pairs. The field list is allocated by the service provider and 
must be deallocated by the application by calling CSSM_CL_FreeFields() (CSSM API), or 
CL_FreeFields() (CL SPI). 
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DESCRIPTION 


This function returns all field values from a prelocated, cached CRL record. The scanned CRL record is 
identified by cr1RecordIndex, which is returned by the function cSSM_CL_IsCert InCachedCr1() (CSSM 
API), or CL_IsCertInCachedCr1() (CL SPI). 


Fields are returned as a set of OID-value pairs. The OID identifies the CRL record field and the data format 
of the value extracted from that field. The Certificate Library module defines and uses a preferred data 
format for returning field values in this function. 


Each CRL record may be digitally signed when it is added to the CRL using the function 
CSSM_CL_CrlAddCert () (CSSM API), or CL_CriAddcert () (CL SPI). This function does not perform any 
signature verification on the CRL record. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CL_INVALID_CACHE_HANDLE 
CSSMERR_CL_INVALID_CRL_INDEX 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 

CSSM_CL_IsCertInCachedCrl, CSSM_CL_CrlCache CSSM_CL_CrlAbortCache CSSM_CL_FreeFidds 
Functions for the CLI SPI: 

CL_IsCertlInCachedCrl, CL_CrilCache, CL_CrlAbortCache, CL_FreeFidds 
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CL_CriGetAllFields 


NAME 
CL_CrlGetAllFields: CSSM_CL_CrlGetAll Fields - Get the field values from the CRL (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 
CSSM_RETURN CSSMAPI CSSM_CL_CrlGetAllFields 
(CSSM_CL_HANDLE CLHandle, 

const CSSM_DATA *Crl, 
uint32 *NumberOfCrlFields, 
CSSM_FIELD_PTR *CrlFields) 
SPI: 
CSSM_RETURN CSSMCLI CL_CrlGetAllFields 
(CSSM_CL_HANDLE CLHandle, 
const CSSM_DATA *Crl, 
uint32 *NumberOfCrlFields, 


CSSM_FIELD_PTR *CrlFields) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CLHandle (input) 


The handle that describes the add-in Certificate Library module used to perform this 
function. 


Crl (input) 


A pointer tothe CSSM_DATA structure that contains the encoded, packed CRL from which 
field values are to be extracted. 


NumberOfCrlFields (output) 
The number of entries in the array CriFields. 
CrlFields (output) 


A pointer to an array of OI D-value pairs that describe the contents of the CRL. The 
extracted CRL fields are returned as the value portion of each OI D-value pair. The field list 
is allocated by the service provider and must be deallocated by the application by calling 
CSSM_CL_FreeFields() (CSSM API), or CL_FreeFields () (CL SPI). 


DESCRIPTION 


This function returns one or more structures. Each structure contains a set of field values from the encoded, 
packed CRL contained in crl. Each structure is returned in the FieldValue entry of the CSSM_FIELD 
structure CrlFields. The parameter NumberOfCri1Fields indicates the number of returned structures. 
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The CRL can be signed or unsigned. This function does not perform any signature verification on the CRL 
fields or the CRL records. Each CRL record can be digitally signed when it is added tothe CRL using the 
function CSSM_CL_CriAddcert () (CSSM API), or CL_CrlAddcert () (CL SPI). 


RETURN VALUE 

A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 

ERRORS 

Errors are described in the CDSA Technical Standard. 


CSSMERR_CL_INVALID_CRL_POINTER 
CSSMERR_CL_UNKNOWN_FORMAT 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 
CSSM_CL_FreeFidds 
Functions for the CLI SPI: 
CL_FreeFidds 
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CL_CriGetFirstCachedFieldValue 


NAME 


CL_CrlGetFirstCachedFieldValue: CSSM_CL_CrlGetFirstCachedF ieldValue - Get field values from 
the cached CRL (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_CL_CrlGetFirstCachedFieldValue 
(CSSM_CL_HANDLE CLHandle, 
CSSM_HANDLE CrlHandle, 
const CSSM_DATA *CrlRecordIndex, 
const CSSM_OID *CrlField, 
CSSM_HANDLE_PTR ResultsHandle, 
uint32 *NumberOfMatchedFields, 
CSSM_DATA_PTR *FieldValue) 
SPI: 
CSSM_RETURN CSSMCLI CL_CrlGetFirstCachedFieldValue 
(CSSM_CL_HANDLE CLHandle, 
CSSM_HANDLE CrlHandle, 
const CSSM_DATA *CrlRecordIndex, 
const CSSM_OID *CrlField, 
CSSM_HANDLE_PTR ResultsHandle, 


uint32 *NumberOfMatchedFields, 
CSSM_DATA_PTR *FieldValue) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CLHandle (input) 


The handle that describes the add-in Certificate Library module used to perform this 
function. 


CrlHandle (input) 


A handle identifying a CRL that the application has temporarily cached with the Certificate 
Library module. The referenced CRL is searched for the field values identified by criField. 


CrlRecordIndex (input/optional) 


An index value identifying a particular revocation record in a cached CRL. If an index value 
is supplied, the scan for the field values identified by criField is limited to the preselected 
revocation record. 


CrlField (input) 
A pointer to an object identifier that identifies the field value to be extracted from the CRL. 


Result sHandle (output) 


A pointer tothe CSSM_HANDLE that should be used to obtain any additional matching 
fields. 


NumberOfMat chedFields (output) 


The total number of fields that match the cr1Field OID. This count includes the first 
match, which was returned by this function. 


FieldValue (output) 


A pointer to the structure containing the value of the requested field. The structure and the 
fidd at I "(*FieldValue) ->Data" are allocated by the service provider. The 
CSSM_CL_FreeFieldvalue () (CSSM API), or CL_FreeFieldValue() (CL SPI), function can 
be used to deallocate *FieldValue and (*FieldValue) ->Data. 


DESCRIPTION 


This function returns a single structure containing a set of field values from the cached CRL identified by 
CrlHandle parameter. The selected fields are designated by the CSSM_OID CriField parameter and 
returned in the output parameter Fieldvalue. The OID alsoidentifies the data format of the values returned 
to the caller. If multiple Ol Ds designate the same CRL field, then each such OID defines a distinct data 
format for the returned values. The function CSSM_CL_Cr1lDescribeFormat () (CSSM API), or 
CL_CrlDescribeFormat () (CL SPI), provides a list of all CSSM_OID values supported by a CL module for 
naming fields of a CRL. 


The search can be limited to a particular revocation record within the CRL. A single record is identified by the 
CrlRecordIndex parameter, which is returned by the function CSSM_CL_IsCertInCachedCr1 () (CSSM API), 
or CL_IsCert InCachedCr1() (CL SPI). If no record index is supplied, the search is initiated from the 
beginning of the CRL. 


The CRL can be signed or unsigned. This function does not perform any signature verification on the CRL 
fields or the CRL records. Each CRL record can be digitally signed when it is added tothe CRL using the 
function CSSM_CL_CrlAddcert () (CSSM API), or CL_criaAddCert () (CL SPI). The caller can examine fields 
inthe CRL and CRL records at any time using this function. 


The CriField OID can identify a single occurrence of a set of CRL fields or multiple occurrences of a set of 
CRL fields. | f the cr1Field OID matches more than one occurrence, this function outputs the total number of 
matches and a ResultsHandle to be used as input to CSSM_Cr1GetNextFieldValue () (CSSM API), or 
CrlGetNextFieldValue() (CL SPI), to retrieve the remaining matches. The first match is returned as the 
return value of this function. 


This function determines the complete set of matches. The number of matches and the selected field values do 
not change between this function and subsequent calls to CSSM_CL_Cr1GetNextFieldValue() (CSSM API), 
or CL_Cr1lGetNextFieldValue() (CL SPI). 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 
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CSSMERR_CL_INVALID_CACHE_HANDLE 
CSSMERR_CL_INVALID_CRL_INDEX 

CSSMERR_CL_UNKNOWN_TAG 
CSSMERR_CL_NO_FIELD_VALUES 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 
Functions for the CSSM API: 
CSSM_CL_CrilGeNexttCachedFiddValue CSSM_CL_IsCertInCachedCrl, CSSM_CL_CrlAbortQuery, 


CSSM_CL_CrIiCache CSSM_CL_CrlAbortCache CSSM_CL_CrlDescribeFormat, CSSM_CL_FreeFiddValue 


Functions for the CLI SPI: 


CL_CrlGetNextCachedF iddValue CL_IsCertIinCachedCrl, CL_CrlAbortQuery, CL_CrliCache, 
CL_CrlAbortCache, CL_CrlDescribeFormat, CL_FreeFiddValue 
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CL_CriGetFirstFieldValue 


NAME 


CL_CrilGetFirstFieldValue CSSM_CL_CrlGetFirstFieldValue - Get the value of the first CRL field 
(CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_CL_CrlGetFirstFieldValue 
(CSSM_CL_HANDLE CLHandle, 

const CSSM_DATA *Crl, 

const CSSM_OID *CrlField, 

CSSM_HANDLE_PTR ResultsHandle, 

uint32 *NumberOfMatchedFields, 

CSSM_DATA_PTR *Value) 

SPL: 
CSSM_RETURN CSSMCLI CL_CrlGetFirstFieldValue 
(CSSM_CL_HANDLE CLHandle, 

const CSSM_DATA *Crl, 

const CSSM_OID *CrlField, 

CSSM_HANDLE_PTR ResultsHandle, 

uint32 *NumberOfMatchedFields, 

CSSM_DATA_PTR *Value) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CLHandle (input) 


The handle that describes the add-in Certificate Library module used to perform this 
function. 


Crl (input) 


A pointer to the CSSM_DATA structure that contains the CRL from which the field is to be 
retrieved. 


CrlField (input) 
An object identifier that identifies the field value to be extracted from the CRL. 
Result sHandle (output) 


A pointer tothe CSSM_HANDLE that should be used to obtain any additional matching 
fields. 


NumberOfMat chedFields (output) 


The total number of fields that match the criField OID. This count includes the first 
match, which was returned by this function. 


Value (output) 


114 


A pointer to the structure containing the value of the requested field. The structure and the 
field at I "(*Value)->Data" are allocated by the service provider. The 
CSSM_CL_FreeFieldValue () (CSSM API), or CL_FreeFieldValue() (CL SPI), function can 
be used to deallocate *value and (*Value) ->Data. 


DESCRIPTION 


This function returns the value of the CRL field designated by the CSSM_OID criField. The OID also 
identifies the data format for the field value returned to the caller. If multiple Ol Ds name the same CRL field, 
then each OID defines a distinct data format for the returned field value. The function 
CSSM_CL_CrlDescribeFormat () (CSSM API), or CL_CrlDescribeFormat () (CL SPI), provides a list of all 
CSSM_OID values supported by a Certificate Library module for naming fields of a CRL. 


If more than one field matches the Cr1Field OID, the first matching field will be returned. The number of 
matching fields is an output parameter, as is the Result sHandl1le to be used to retrieve the remaining 
matching fields. 


The set of matching fields is determined by this function. The number of matching fields and the field values 
do not change between this function and subsequent calls to CSSM_CL_Cr1GetNextFieldValue() (CSSM 
API), or CL_CrlGetNextFieldValue() (CL SPI). 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CL_INVALID_CRL_POINTER 
CSSMERR_CL_UNKNOWN_FORMAT 
CSSMERR_CL_UNKNOWN_TAG 
CSSMERR_CL_NO_FIELD_VALUES 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 

CSSM_CL_CrIG&NextFiddValue CSSM_CL_CrlAbortQuery, CSSM_CL_CriIGeAllFidds 
Functions for the CLI SPI: 

CL_CriGetNextFiddValue CL_CrlAbortQuery, CL_CrIGetAllFidds 
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CL_CriGetNextCachedFieldValue 


NAME 


CL_CrlGetNextCachedF ieldValue: CSSM_CL_CrlGetN extCachedF ieldValue - Get the value of the 
next cached CRL field (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_CL_CrlGetNextCachedFieldValu 
(CSSM_CL_HANDLE CLHandle, 

CSSM_HANDLE ResultsHandle, 

CSSM_DATA_PTR *FieldValue) 

SPI: 
CSSM_RETURN CSSMCLI CL_CrlGetNextCachedFieldValu 
(CSSM_CL_HANDLE CLHandle, 

CSSM_HANDLE ResultsHandle, 

CSSM_DATA_PTR *FieldValue) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CLHandle (input) 


The handle that describes the add-in Certificate Library module used to perform this 
function. 


Result sHandle (input) 
The handle that identifies the results of a CRL query. 
FieldValue (output) 


A pointer to the structure containing the value of the requested field. The structure and the 
field at I "(*FiledValue) ->Data" are allocated by the service provider. The 
CSSM_CL_FreeFieldValue() (CSSM API), or CL_FreeFieldValue() (CL SPI), function can 
be used to deallocate *FieldValue and (*FieldValue) ->Data. 


DESCRIPTION 


This function returns the value of a CRL field, when that field occurs multiple times ina CRL. CRLs with 
repeated fields (such as revocation records) have multiple field values corresponding toa single OID. A call to 
the function CSSM_CL_CrlGetFirstCachedFieldValue() (CSSM API), or 
CL_CrlGetFirstCachedFieldvalue() (CL SPI), initiates the process and returns a ResultsHandle 
identifying the size and values contained in the result set. The cSSM_CL_Cr1GetNext CachedFieldValue () 
(CSSM API), or CL_CrlGetNextCachedFieldValue() (CL SPI), function can be called repeatedly to obtain 
these values, one at a time. The result set does not change in size or value between calls to this function. 


The result set selected by CSSM_CL_Cr1GetFirstCachedFieldValue() (CSSM API), or 
CL_CrlGetFirstCachedFieldvalue() (CL SPI), and identified by ResultsHandle can reference CRL fields 
repeated across multiple revocation records or within one revocation record. The scope of the scan was set by 
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an optional Cr1RecordIndex input to the function CSSM_CL_CrlGetFirstCachedFieldValue() (CSSM API), 
or CL_CrlGetFirstCachedFieldValue() (CL SPI). If the record index was specified, then the results set is 
the revocation record identified by the index. If no record index was specified, then the results set can include 
repeated fields from multiple revocation records in aCRL. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CL_INVALID_RESULTS_HANDLE 
CSSMERR_CL_NO_FTELD_VALUES 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 


Functions for the CSSM API: 


CSSM_CL_CrlGe@tFirstCachedFiddValue, CSSM_CL_CrlAbortQuery, CSSM_CL_IsCertInCachedCrl, 
CSSM_CL_CriCamhe CSSM_CL_CrlAbortCache CSSM_CL_FreeFiddValue 


Functions for the CLI SPI: 


CL_CrlGetFirstCachedFiddValue, CL_CrlAbortQuery, CL_IsCertIinCachedCrl, CL_CriCache 
CL_CrlAbortCache CL_FreeFiddValue 
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CL_CriGetNextFieldValue 


NAME 


CL_CriGetNextFieldValue: CSSM_CL_CrlGetNextFieldValue- Get the value of the next CRL field 
(CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_CL_CrlilGetNextFieldValu 
(CSSM_CL_HANDLE CLHandle, 

CSSM_HANDLE ResultsHandle, 

CSSM_DATA_PTR *Value) 

SPI: 
CSSM_RETURN CSSMCLI CL_CrlGetNextFieldValu 
(CSSM_CL_HANDLE CLHandle, 

CSSM_HANDLE ResultsHandle, 

CSSM_DATA_PTR *Value) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CLHandle (input) 


The handle that describes the add-in Certificate Library module used to perform this 
function. 


Result sHandle (input) 
The handle that identifies the results of a CRL query. 
Value (output) 


A pointer to the structure containing the value of the requested field. The structure and the 
field at I "(*Value)->Data" are allocated by the service provider. The 
CSSM_CL_FreeFieldValue() (CSSM API), or CL_FreeFieldValue() (CL SPI), function can 
be used to deallocate *value and (*Value) ->Data. 


DESCRIPTION 


This function returns the value of a CRL field, when that field occurs multiple times ina CRL. CRLs with 
repeated fields (such as revocation records) have multiple field values corresponding toa single OID. A call to 
the function CSSM_CL_Cr1GetFirstFieldValue() (CSSM API), or CL_CrlGetFirstFieldvalue() (CL SPI), 
initiates the process and returns a results handle identifying the size and values contained in the result set. 
The CSSM_CL_Cr1GetNextFieldvalue() (CSSM API), or CL_CrlGetNextFieldValue() (CL SPI), function 
can be called repeatedly to obtain these values, one at a time. The result set does not change in size or value 
between calls to this function. 
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RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 


indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CL_INVALID_RESULTS_HANDLE 
CSSMERR_CL_NO_FTELD_VALUES 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 
CSSM_CL_CrlGe@FirstFiddValue CSSM_CL_CrlAbortQuery 
Functions for the CLI SPI: 

CL_CrilGetFirstFiddValue, CL_CrlAbortQuery 
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CL_CriRemoveCert 


NAME 
CL_CriRemoveCert: CSSM_CL_CrlRemoveCert - Reinstate a certificate (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_CL_CrlRemoveCert 
(CSSM_CL_HANDLE CLHandle, 

const CSSM_DATA *Cert, 

const CSSM_DATA *OldCrl, 

CSSM_DATA_PTR NewCr1) 

SPI: 
CSSM_RETURN CSSMCLI CL_CrlRemoveCert 
(CSSM_CL_HANDLE CLHandle, 

const CSSM_DATA *Cert, 

const CSSM_DATA *OldCrl, 
CSSM_DATA_PTR NewCr1) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CLHandle (input) 


The handle that describes the add-in Certificate Library module used to perform this 
function. 


Cert (input) 
A pointer tothe CSSM_DATA structure containing the certificate to be reinstated. 
OldCrl (input) 


A pointer tothe CSSM_DATA structure containing the CRL from which the certificate is to 
be removed. 


NewCrl (output) 


A pointer to the CSSM_DATA structure containing the updated CRL. The NewCr1->Data is 
allocated by the service provider and must be deallocated by the application. 


DESCRIPTION 


This function reinstates a certificate by removing it from the specified CRL. The operation is valid only if the 
CRL has not been closed by the process of signing the CRL by executing CSSM_CL_Cr1Sign()(CSSM API), or 
CL_CriSign() (CL SPI). Once the CRL has been signed, entries cannot be added or removed. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 
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ERRORS 


Errors are described in the CDSA Technical Standard. 


CSSMERR_CL_INVALID_CERT_POINTER 
CSSMERR_CL_INVALID_CRL_POINTER 
CSSMERR_CL_UNKNOWN_FORMAT 
CSSMERR_CL_CRL_ALREADY_SIGNED 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 
CSSM_CL_CrlAddCet 
Functions for the CLI SPI: 
CL_CrlAddCet 
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CL_CriSetFields 


NAME 
CL_CrlSetFields: CSSM_CL_CrlSetFields - Set new field values (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_CL_CrlSetFields 
(CSSM_CL_HANDLE CLHandle, 

uint32 NumberOfFields, 

const CSSM_FIELD *CrlTemplate, 

const CSSM_DATA *OldCrl, 

CSSM_DATA_PTR ModifiedCrl) 

SPI: 
CSSM_RETURN CSSMCLI CL_CrlSetFields 
(CSSM_CL_HANDLE CLHandle, 

uint32 NumberOfFields, 

const CSSM_FIELD *CrlTemplate, 
const CSSM_DATA *OldCrl, 
CSSM_DATA_PTR ModifiedCr1l) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CLHandle (input) 


The handle that describes the add-in Certificate Library module used to perform this 
function. 


NumberOfFields (input) 
The number of OID value pairs specified in the CriTemplate input parameter. 
CrlTemplate (input) 


Any array of field OID value pairs containing the values to initialize the CRL attribute 
fields. 


OldCrl (input) 


The CRL to be updated with the new attribute values. The CRL must be unsigned and 
available for update. 


ModifiedCrl (output) 


A pointer to the modified, unsigned CRL. The ModifiedCrl->Data is allocated by the 
service provider and must be deallocated by the application. 
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DESCRIPTION 


This function will set the fields of the input CRL to the new values, specified by the input Ol D/value pairs. If 
there is more than one possible instance of an OID (for example, as in an extension or CRL record), then a 
new field with the specified value is added tothe CRL. 


This function should be used to update any of the CRL field values. If a specified field was initialized by 
CSSM_CL_CrlCreateTemplate() (CSSM API), or CL_CrlCreateTemplate() (CL SPI), the field value is set to 
the new specified value. If a specified field was not initialized by the cssM_CL_CricreateTemplate() (CSSM 
API), or CL_CrlCreateTemplate() (CL SPI), the field is set to the new specified value. The oldcri must be 
unsigned. Once a CRL has been signed using CSSM_CL_Cr1Sign() (CSSM API), or CL_cr1Sign() (CL SPI), 
the signed CRL's field values cannot be modified. Modification would invalidate the cryptographic signature 
of the CRL. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CL_INVALID_FIELD_POINTER 
CSSMERR_CL_UNKNOWN_TAG 
CSSMERR_CL_INVALID_NUMBER_OF_FIELDS 
CSSMERR_CL_UNKNOWN_FORMAT 
CSSMERR_CL_INVALID_CRL_POINTER 
CSSMERR_CL_CRL_ALREADY_SIGNED 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 


Functions for the CSSM API: 


CSSM_CL_CrlCreateTenplate, CSSM_CL_CrlAddCet, CSSM_CL_CrlSign, 
CSSM_CL_CertGeF irstFiddValue 


Functions for the CLI SPI: 
CL_CrlCreateTemplate, CL_CriAddCert, CL_CrlSign, CL_CertGe@FirstFiddValue 
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CL _CrlSign 
NAME 
CL_CrlSign: CSSM_CL_CrlSign, CL_CrlSign - Sign a CRL (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_CL_CrlSign 
(CSSM_CL_HANDLE CLHandle, 
CSSM_CC_HANDLE CCHandle, 

const CSSM_DATA *UnsignedCrl, 

const CSSM_FIELD *SignScope, 

uint32 ScopeSize, 

CSSM_DATA_PTR SignedCr1l) 

SPI: 
CSSM_RETURN CSSMCLI CL_CrlSign 
(CSSM_CL_HANDLE CLHandle, 
CSSM_CC_HANDLE CCHandle, 

const CSSM_DATA *UnsignedCrl, 
const CSSM_FIELD *SignScope, 
uint32 ScopeSize, 
CSSM_DATA_PTR SignedCr1l) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CLHandle (input) 


The handle that describes the add-in Certificate Library module used to perform this 
function. 


CCHandle (input) 

The handle that describes the context of this cryptographic operation. 
UnsignedCrl (input) 

A pointer tothe CSSM_DATA structure containing the CRL to be signed. 
SignScope (input/optional) 


A pointer tothe CSSM_FIELD array containing the tag/value pairs of the fields to be 
signed. I f the signing scope is null, the Certificate Library module includes a default set of 
CRL fields in the signing process. 


ScopeSize (input) 


The number of entries in the sign scope list. If the signing scope is not specified, the input 
scope size must be zero. 


SignedCr1 (output) 
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A pointer tothe CSSM_DATA structure containing the signed CRL. The SignedCr1->Data 
is allocated by the service provider and must be deallocated by the application. 


DESCRIPTION 


This function signs a CRL using the private key and signing algorithm specified in the ccHandle parameter. 
The result is a signed, encoded certificate revocation list in Signedcri. The unsigned CRL is specified in the 
input UnsignedCri. The Unsignedcr1 is constructed using the CSSM_CL_Cr1CreateTemplate (), 
CSSM_CL_CrlSetFields(), CSSM_CL_CrlAddCert (), and CSSM_CL_CrlRemoveCert () functions (for the 
CSSM API), or their CL SPI equivalents. 


The ccHandle must be context created using the function CSSM_CSP_CreateSignatureContext () (CSSM 
API), or CSP_CreateSignatureContext () (SPI). The context must specify the Cryptographic Services 
Provider module, the signing algorithm, and the signing key that must be used to perform this operation. The 
context must also provide the passphrase or a callback function to obtain the passphrase required to access 
and use the private key. 


The fields included in the signing operation are identified by the OI Ds in the optional SignScope array. 


Once the CRL has been signed it cannot be modified. This means that entries cannot be added or removed 
from the CRL through application of the cSSM_CL_CrlAddCert () or 
CSSM_CL_CrlRemoveCertCSSM_CL_CrlRemoveCert () (or their CL SPI equivalent operations. A signed CRL 
can be verified, applied to a data store, and searched for values. 


The memory for the Signedcr1l->Data output is allocated by the service provider using the calling 
application's memory management routines. The application must deallocate the memory. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 

Errors are described in the CDSA Technical Standard. 
CSSMERR_CL_INVALID_CONTEXT_HANDLE 
CSSMERR_CL_INVALID_CRL_POINTER 
CSSMERR_CL_UNKNOWN_FORMAT 
CSSMERR_CL_INVALID_FIELD_POINTER 
CSSMERR_CL_UNKNOWN_TAG 
CSSMERR_CL_INVALID_SCOPE 
CSSMERR_CL_SCOPE_NOT_SUPPORTED 
CSSMERR_CL_INVALID_NUMBER_OF_FIELDS 
CSSMERR_CL_CRL_ALREADY_SIGNED 

SEE ALSO 

Books 


Inta CDSA Application Devdoper's Guide 


Online Help 
Functions for the CSSM API: 
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Functions: 

CSSM_CL _CrlVerify, CSSM_CL_CrlVerifyWithK ey 
Functions for the CLI SPI: 

CL_CrlVerify, CL_CrlVerifyWithKey 
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CL _CrliVerify 


NAME 
CL_CrlVerify: CSSM_CL_CrlVerify - Verify a signed CRL has not been altered (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_CL_CrlVerify 
(CSSM_CL_HANDLE CLHandle, 
CSSM_CC_HANDLE CCHandle, 

const CSSM_DATA *CrlToBeVerified, 
const CSSM_DATA *SignerCert, 

const CSSM_FIELD *VerifyScope, 

uint32 ScopeSize) 

SPI: 
CSSM_RETURN CSSMCLI CL_CrlVerify 
(CSSM_CL_HANDLE CLHandle, 
CSSM_CC_HANDLE CCHandle, 

const CSSM_DATA *CrlToBeVerified, 
const CSSM_DATA *SignerCert, 
const CSSM_FIELD *VerifyScope, 
uint32 ScopeSize) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CLHandle (input) 


The handle that describes the add-in Certificate Library module used to perform this 
function. 


CCHand1e (input/optional) 

The handle that describes the context of this cryptographic operation. 
CrlToBeVerified (input) 

A pointer tothe CSSM_DATA structure containing the CRL to be verified. 
SignerCert (input/optional) 

A pointer tothe CSSM_DATA structure containing the certificate used to sign the CRL. 
VerifyScope (input/optional) 


A pointer tothe CSSM_FIELD array containing the tag/value pairs of the fields to be 
verified. If the verification scope is null, the Certificate Library module assumes that a 
default set of fields were used in the signing process and those same fields are used in the 
verification process. 


ScopeSize (input) 
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The number of entries in the verify scope list. If the verification scope is not specified, the 
input value for scope size must be zero. 


DESCRIPTION 


This function verifies that the signed CRL has not been altered since it was signed by the designated signer. 
It does this by verifying the digital signature over the fields specified by the verifyScope parameter. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CL_INVALID_CONTEXT_HANDLE 
CSSMERR_CL_INVALID_CERT_POINTER 
CSSMERR_CL_INVALID_CRL_ POINTER 
CSSMERR_CL_UNKNOWN_FORMAT 
CSSMERR_CL_INVALID_ FIELD POINTER 
CSSMERR_CL_UNKNOWN_TAG 
CSSMERR_CL_INVALID_SCOPE 
CSSMERR_CL_INVALID_NUMBER_OF_FIELDS 
CSSMERR_CL_SCOPE_NOT_SUPPORTED 
CSSMERR_CL_ VERIFICATION _ FATLURE 
SEE ALSO 

Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 
CSSM_CL_CrlSign 
Functions for the CLI SPI: 
CL_CrlSign 
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CL_CriVerifyWithKey 


NAME 
CL_CrlVerifyWithK ey: CSSM_CL_CrlVerifyWithK ey - Verify a CRL with a specific key (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_CL_CrlVerifyWithKey 
(CSSM_CL_HANDLE CLHandle, 

CSSM_CC_HANDLE CCHandle, 

const CSSM_DATA *CrlToBeVerified) 

SPE: 
CSSM_RETURN CSSMCLI CL_CrlVerifyWithKey 
(CSSM_CL_HANDLE CLHandle, 
CSSM_CC_HANDLE CCHandle, 


const CSSM_DATA *CrlToBeVerified) 


LIBRARY 


Common Security Services Manager library (cdsa$Sincssm300_shr.exe) 


PARAMETERS 


CLHandle (input) 


The handle that describes the Certificate Library service module used to perform this 
function. 


CCHandle (input) 


A signature verification context defining the Cryptographic Services Provider (CSP), 
verification algorithm, and public key that must be used to perform the operation. 


CrlToBeVerified (input) 


A signed certificate revocation list whose signature is to be verified. 


DESCRIPTION 


This function verifies that the Cr1ToBeVerified parameter was signed using a specific private key and that 
the certificate revocation list has not been altered since it was signed using that private key. The public key 
corresponding to the private signing key is used in the verification process. 


The cryptographic context indicated by the ccHandle parameter must be a signature verification context 
created using the function cSSM_CSP_CreateSignatureContext () (CSSM API) or 
CSP_CreateSignatureContext () (CL SPI). The context must specify the Cryptographic Services Provider 
(CSP) module, the verification algorithm, and the public verification key that must be used to perform this 
operation. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 
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ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CL_INVALID_CONTEXT_HANDLE 
CSSMERR_CL_INVALID_CRL_ POINTER 
CSSMERR_CL_UNKNOWN_FORMAT 
CSSMERR_CL_VERIFICATION_ FATLURE 
Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 
CSSM_CL_CrlVerify 
Functions for the CLI SPI: 
CL_CrlVerify 
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CL _FreeFields 


NAME 
CL_FreeFields: CSSM_CL_FreeFields - Free fields (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_CL_FreeFields 
(CSSM_CL_HANDLE CLHandle, 

uint32 NumberOfFields, 

CSSM_FIELD_PTR *FieldArray) 

SPI: 
CSSM_RETURN CSSMCLI CL_FreeFields 
(CSSM_CL_HANDLE CLHandle, 

uint32 NumberOfFields, 
CSSM_FIELD_PTR *FieldArray) 


LIBRARY 


Common Security Services Manager library (cdsa$Sincssm300_shr.exe) 


PARAMETERS 


CLHandle (input) 


The handle that describes the add-in Certificate Library module used to perform this 
function. 


NumberOfFields (input) 
The length of the array of fields in FieldArray. 
FieldArray (input) 
A pointer to an array of CSSM_FIELD structures that need to be deallocated. 


DEFINITIONS 


This function frees the fields in the FieldArray by freeing the data pointers for both the Fieldoid and 
Fieldvalue fields. It also frees the top level FieldArray pointer. 


This function should be used only to free CSSM_FIELD_PTR values returned from calls 
CSSM_TP_CertGetAllTemplateFields (), CSSM_CL_CertGetAllTemplateFields(), 
CSSM_CL_CertGetAllFields (), CSSM_CL_CrlGetAllFields(), 
CSSM_CL_Cr1GetAl11CachedRecordFields (), or their SPI equivalent calls. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 
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ERRORS 
Errors are described in the CDSA Technical Standard. 


None specific to this call. 


SEE ALSO 
Inta CDSA Application Devdoper's Guide 
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CL _FreeFieldValue 
NAME 
CL_FreeFieldValue: CSSM_CL _FreeFieldValue- Free field data (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 


CSSM_RETURN CSSMAPI CSSM_CL_FreeFieldValue 
(CSSM_CL_HANDLE CLHandle, 

const CSSM_OID *CertOrCrlOid, 
CSSM_DATA_PTR Value) 

SPI: 
CSSM_RETURN CSSMCLI CL_FreeFieldValue 
(CSSM_CL_HANDLE CLHandle, 

const CSSM_OID *CertOrCrlOid, 
CSSM_DATA_PTR Value) 


LIBRARY 


Common Security Services Manager library (cdsa$Sincssm300_shr.exe) 


PARAMETERS 


CLHandle (input) 


The handle that describes the add-in Certificate Library module used to perform this 
function. 


CertOrCrl0id (input) 

A pointer tothe CSSM_OID structure describing the type of the Value to be freed. 
Value (input) 

A pointer tothe CSSM_DATA structure containing the Data to be freed. 


DESCRIPTION 


This function frees the data specified by value and value->Data. CertOrCr10id indicates the type of the 
data in value. 


This function should be used only to free CSSM_DATA values returned from calls 
CSSM_CL_CertGetFirstFieldValue(), CSSM_CL_CertGetNextFieldValue(), 
CSSM_CL_CertGetFirstCachedFieldValue(), CSSM_CL_CertGetNextCachedFieldValue(), 
CSSM_CL_CrlGetFirstFieldValue(),CSSM_CL_CrlGetNextFieldValue(), 
CSSM_CL_Cr1GetFirstCachedFieldValue(), CSSM_CL_CrlGetNextCachedFieldValue (), or their CLI SPI 
equivalents. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 
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ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CL_UNKNOWN_TAG 


SEE ALSO 
Inta CDSA Application Devdoper's Guide 
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CL_IsCertinCachedCrl 
NAME 
CL_IsCertlnCachedCrl: CSSM_CL_IsCertl nCachedCrl - Search cached CRL for a record (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_CL_IsCertInCachedCrl 
(CSSM_CL_HANDLE CLHandle, 

const CSSM_DATA *Cert, 

CSSM_HANDLE CrlHandle, 
CSSM_BOOL *CertFound, 
CSSM_DATA_PTR CrlRecordIndex) 
SPI: 
CSSM_RETURN CSSMCLI CL_IsCertInCachedCrl 
(CSSM_CL_HANDLE CLHandle, 

const CSSM_DATA *Cert, 

CSSM_HANDLE CrlHandle, 

CSSM_BOOL *CertFound, 

CSSM_DATA_ PTR CrlRecordIndex) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CLHandle (input) 


The handle that describes the add-in Certificate Library module used to perform this 
function. 


Cert (input) 
A pointer tothe CSSM_DATA structure containing an encoded, packed certificate. 
CrlHandle (input) 


A handle identifying a CRL that the application has temporarily cached with the Certificate 
Library module. The referenced CRL is searched for a revocation record matching the 
specified Cert. 


CertFound (output) 


A pointer toa CSSM_BOOL indicating success or failure in finding the specified certificate 
inthe CRL. CSSM_TRUE signifies that the certificate was found in the CRL. 
CSSM_FALSE indicates that the certificate was not found in the CRL. 


CrlRecordIndex (output) 


A pointer toa CSSM_DATA structure containing an index descriptor for direct access to the 
located CRL record. Cr1RecordIndex->Data is allocated by the service provider and must 
be deallocated by the application. 
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DESCRIPTION 


This function searches the cached CRL for a record corresponding to the certificate. The result of the search is 
returned in CertFound. TheCRL and the records within the CRL must be digitally signed. This function does 
not verify either signature. The caller should use CSSM_TP_CrlVerify() Of CSSM_CL_CriVerify () (or their 
SPI equivalents) before invoking this function. Once the CRL has been verified, the caller can invoke this 
function repeatedly without repeating the verification process. 


If the certificate is found in the CRL, the CL module returns an index descriptor CrlRecordIndex for use 
with other Certificate Library CRL functions. The index provides more direct access to the selected CRL 
record. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CL_INVALID_CERT_POINTER 
CSSMERR_CL_UNKNOWN_FORMAT 
CSSMERR_CL_INVALID_CACHE_HANDLE 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 
Functions for the CSSM API: 


CSSM_CL_CrlGetFirstCachedFiddValue, CSSM_CL_CriGetNextCachedFiddValue 
CSSM_CL_CrlGetAllCachedRecordFidd, CSSM_CL_CrlCache, CSSM_CL_CrlAbortCache 


Functions for the CLI SPI: 


CL_CrlGetFirstCachedFiddValue, CL_CrlGa&NextCachedFiddValue, CL_CrlGetAllCachedRecordF idd, 
CL_CrlCache, CL_CrlAbortCache 
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CL_IsCertinCrl 


NAME 
CL_IsCertInCrl: CSSM_CL_IsCertInCrl - Search CRL for a certificate record (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_CL_IsCertInCrl 
(CSSM_CL_HANDLE CLHandle, 

const CSSM_DATA *Cert, 

const CSSM_DATA *Crl, 

CSSM_BOOL *CertFound) 

SPI: 
CSSM_RETURN CSSMCLI CL_IsCertIncCrl 
(CSSM_CL_HANDLE CLHandle, 

const CSSM_DATA *Cert, 

const CSSM_DATA *Crl, 

CSSM_BOOL *CertFound) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CLHandle (input) 


The handle that describes the add-in Certificate Library module used to perform this 
function. 


Cert (input) 

A pointer tothe CSSM_DATA structure containing the certificate to be located. 
Crl (input) 

A pointer tothe CSSM_DATA structure containing the CRL to be searched. 
CertFound (output) 


A pointer toa CSSM_BOOL indicating success or failure in finding the specified certificate 
inthe CRL. CSSM_TRUE signifies that the certificate was found in the CRL. 
CSSM_FALSE indicates that the certificate was not found in the CRL. 


DESCRIPTION 


This function searches the CRL for a record corresponding to the certificate. The result of the search is 
returned in CertFound. TheCRL and the records within the CRL must be digitally signed. This function does 
not verify either signature. The caller should use CSSM_TP_CrlVerify() Of CSSM_CL_CriVerify () (or their 
SPI equivalents) before invoking this function. Once the CRL has been verified, the caller can invoke this 
function repeatedly without repeating the verification process. 
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RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CL_INVALID_CERT_POINTER 
CSSMERR_CL_INVALID_CRL_POINTER 
CSSMERR_CL_UNKNOWN_FORMAT 


SEE ALSO 
Inta CDSA Application Devdoper's Guide 
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CL_PassThrough 


NAME 
CL_PassThrough: CSSM_CL_PassThrough - Extend certificate library functionality (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_CL_PassThrough 
(CSSM_CL_HANDLE CLHandle, 
CSSM_CC_HANDLE CCHandle, 

uint32 PassThroughId, 

const void *InputParams, 

void **OutputParams) 

SP Ls 
CSSM_RETURN CSSMCLI CL_PassThrough 
(CSSM_CL_HANDLE CLHandle, 
CSSM_CC_HANDLE CCHandle, 

uint32 PassThroughId, 

const void *InputParams, 

void **OutputParams) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CLHandle (input) 


The handle that describes the add-in Certificate Library module used to perform this 
function. 


CCHand1e (input/optional) 


The handle that describes the context of the cryptographic operation. If the module-specific 
operation does not perform any cryptographic operations, a cryptographic context is not 
required. 


PassThroughId (input) 
An identifier assigned by the CL module to indicate the exported function to perform. 
InputParams (input/optional) 


A pointer to a module, implementation-specific structure containing parameters to be 
interpreted in a function-specific manner by the requested CL module. 


Output Params (output/optional) 


A pointer to a module, implementation-specific structure containing the output data. The 
service provider allocates the memory for substructures. The application must free the 
memory for the substructures. 
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DESCRIPTION 


This function allows applications to call certificate library module-specific operations. Such operations might 
include queries or services that are specific to the domain represented by the CL module. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CL_INVALID_CONTEXT_HANDLE 
CSSMERR_CL_INVALID_PASSTHROUGH_ID 
CSSMERR_CL_INVALID_DATA 


SEE ALSO 
Inta CDSA Application Devdoper's Guide 
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CSP_EventNotify 
NAME 


CSP_EventNotify - Notify service module of a context event 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMSPI CSP_EventNotify 


(CSSM_MODULE_HANDLE CSPHandle, 


CSSM_CONTEXT_EVENT Event, 


CSSM_CC_HANDLE CCHandle, 


const CSSM_CONTEXT *Context) 


The CSP_EventNotify( ) function is used by the CSSM Core to interact with the CSP module. Because this 
function is exposed to CSSM only as a function pointer, the function name internal to the CSP can be assigned 
at the discretion of the CSP module developer. However, the parameter list and return value types must 


match those defined for this function. 


PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform calls to CSSM for the memory functions managed by CSSM. 


Event (input) 


One of the following event types listed: 


Event 


Description 


CSSM_CONTE 


XT_E 


ENT_CREATE 


CSSM_CONTE 


XT_E 


CSSM_CONT 


EXT_E 


ENT_UPDATE 


ant 


A caller using this module attach handle has created 
a new cryptographic context using 
CSSM_Create***Context. 


A caller using this module attach handle has deleted 
a cryptographic context using 
CSSM_DeleteContext (). 


A caller using this module attach handle has updated 
an existing cryptographic context. 


CCHandle (input) 


The cryptographic context handle for the context affected by the event. 


Context 


A pointer to the cryptographic context affected by the event. The results of the event are 
visible in the context. 
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DESCRIPTION 


This function is used to notify the service module of a context event related to a particular attach handle. 
Valid events include creation, deletion, or modification of a cryptographic context. The service module can 
examine the new or modified context referenced by pcontext to determine whether the context is acceptable 
to the service module. 


If the cryptographic context is acceptable (if the service module examines the contents of the context only 
upon use of the context), then the service module should return cSsM_oK. If the cryptographic context is not 
acceptable, then the service module should return CSSM_FAIL. 


Upon receiving a return value of cSSM_oK, CSSM completes the operation signaled by this event and returns 
to the calling application. If the return value is cSSM_FAIL, CSSM deletes a newly created context or 
modifications to an existing context, and returns the failed result to the calling application. When deleting a 
cryptographic context, CSSM always returns success to the calling application. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 


Functions: 


CSSM_CSP_CreateSignatureContext, CSSM_CSP_CreateDigestContext, 
CSSM_CSP_CreateSymmetricContext, CSSM_CSP_CreateMacContett, 
CSSM_CSP_CreateRandomGenContext, CSSM_CSP_CreateAsymmetricContext, 
CSSM_CSP_CreateDeriveK eyContext, CSSM_CSP_Create&KeyGenContett, 
CSSM_CSP_CreatePassT hroughContext, CSSM_Dede&teContext, CSSM_UpdateContextAttributes 
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cssm_CcToHandle 


NAME 
cssm_CcToHandle - Get the module attach handle (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI cssm_CcToHandle 
(CSSM_CC_HANDLE Cc, 
CSSM_MODULE_HANDLE PTR ModuleHandle) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


Ce (input) 
A handle identifying a cryptographic context. 
ModuleHandle (output) 


A service provider's module attach handle. This value will be set to 
CSSM_INVALID_HANDLE if the function fails. 


DESCRIPTION 


This function returns the module attach handle identifying the service module that is managing the specified 
cryptographic context. 


The entry point to this function is provided to a service module in a table of upca11 functions passed to the 
service provider during module attach processing. 


If the PVC checking for service providers is on, the service provider has to introduce itself before calling this 
function. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 
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CSSM_ChangeKeyAcl 


NAME 
CSSM_ChangeK eyAcl - Edit a stored ACL associated with the target key (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_ChangeKeyAcl 
(CSSM_CSP_HANDLE CSPHandle, 

const CSSM_ACCESS_ CREDENTIALS *AccessCred, 
const CSSM_ACL_EDIT *AclEdit, 

const CSSM_KEY *Key) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CSPHandle (input) 


The module handle that identifies the Cryptographic Service Provider to perform this 
operation 


AccessCred (input) 


A pointer to the set of one or more credentials used to authenticate and validate the caller's 
authorization to modify the ACL associated with the key. Required credentials can include 
zero or more certificates, zero or more caller names, and one or more samples. | f certificates 
and/or caller names are provided as input, these must be provided as immediate values in 
this structure. Thesamples can be provided as immediate values or can be obtained through 
a callback function included in the AccessCred structure. 


AclEdit (input) 


A structure containing information that defines the edit operation. Valid operations include: 
adding, replacing, and deleting entries in an ACL managed by the service provider. The 
AclEdit can contain information for anew ACL entry and a handle uniquely identifying an 
existing ACL entry. The information controls the edit operation as follows: 


Value of AclE dit.E ditMode Use of AclEdit.NewE ntry and 
AclE dit.OldE ntryHandle 


CSSM_ACL_EDIT_MODE_ADD Adds a new ACL entry to the set of ACL entries 
associated with the specified Key. The new ACL entry is 
created from the ACL entry prototype contained in 
NewEntry. OldEnt ryHandle is ignored for this edit mode. 


CSSM_ACL_EDIT_MODE_DELETE Deletes the ACL entry identified by OldEntryHandle 
and associated with the specified Key. NewEnt ry iS 
ignored for this edit mode. 
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Value of AclEdit.E ditMode Use of AclEdit.NewE ntry and 
AclE dit.OldE ntryHandle 


CSSM_ACL_EDIT_MODE_REPLACE Replaces the ACL entry identified by oldEntryHandle 
and associated with the specified Key. The existing ACL 
is replaced based on the ACL entry prototype contained 
in the NewEntry. 


When replacing an existing ACL entry, the caller must replace all of the items in an ACL 
entry. The replacement prototype includes: 


Subject type and value 


A CSSM_LIST structure containing a typed Subject. The Subject 
identifies the entity authorized by this ACL entry. 


Delegation flag 


A CSSM_BOOL value indicating whether the subject can delegate the 
permissions recorded in the authorization array. 


Authorization array 


A CSSM_AUTHORIZATIONGROUP structure defining the set of 
operations for which permission is granted to the Subject. 


Validity period 


A CSSM_ACL_VALIDITY_PERIOD structure containing two elements, 
the start time and the stop time for which the ACL entry is valid. 


ACL entry tag 


A CSSM_STRING containing a user-defined value associated with the 
ACL entry. 


Key (input) 
A pointer to the target key whose associated ACL is being modified. 


DESCRIPTION 


This function edits the stored ACL associated with the target key. The ACL is modified according to the edit 
mode and information provided in AclEdit. 


The caller must be authorized to modify the target ACL. Caller authentication and authorization to edit the 
ACL is determined based on the caller-provided AccessCred. 


The caller must be authorized to add, delete, or replace the ACL entries associated with the target key. When 
adding or replacing an ACL entry, the service provider must reject the creation of duplicate ACL entries. 


When adding a new ACL entry toan ACL, the caller must provide a complete ACL entry prototype. All ACL 
entry items, except the ACL entry Subject must be provided as an immediate value in AclEdit->NewEntry. 
TheACL entry Subject can be provided as an immediate value, from a verifier with a protected data path, 
from an external authentication or authorization service, or through a callback function specified in 
AclEdit-—>NewEntry-—>Callback. 
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RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


None specific to this call. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 
Functions: CSSM_GeKeAcl 
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CSSM_ChangeKeyOwner 
NAME 
CSSM_ChangeK eyOwner - Change the owner of a key (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_ChangeKeyOwner 
(CSSM_CSP_HANDLE CSPHandle, 

const CSSM_ACCESS_ CREDENTIALS *AccessCred, 
const CSSM_KEY *Key, 
const CSSM_ACL_OWNER_PROTOTYPE *NewOwner) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CSPHandle (input) 


The module handle that identifies the Cryptographic Service Provider to perform this 
operation. 


AccessCred (input) 


A pointer to the set of one or more credentials used to prove the caller is the current Oowner 
of the key. Required credentials can include zero or more certificates, zero or more caller 
names, and one or more samples. | f certificates and/or caller names are provided as input, 
these must be provided as immediate values in this structure. The samples can be provided 
as immediate values or can be obtained through a callback function included in the 
AccessCred structure. 


Key (input) 
A pointer to the target key whose associated Owner is changed. 


NewOwner (Input) 
A CSSM_ACL_OWNER PROTOTYPE defining the new owner of the key. 


DESCRIPTION 
This function takes a CSSM_ACL_OWNER_PROTOTYPE defining the new owner of the key. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 
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None specific to this call. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 
Functions: CSSM_ GetkKeyOwne 
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CSSM_CSP_ChangeL oginAcl 
NAME 
CSSM_CSP_ChangeLoginAdcl - Edit a stored CSP ACL login session (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_CSP_ChangeLoginAcl 
(CSSM_CSP_HANDLE CSPHandle, 

const CSSM_ACCESS_ CREDENTIALS *AccessCred, 
const CSSM_ACL_ EDIT *AclEdit) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CSPHandle (input) 


The module handle that identifies the Cryptographic Service Provider to perform this 
operation 


AccessCred (input) 


A pointer to the set of one or more credentials used to authenticate and validate the caller's 
authorization to modify the ACL controlling login sessions with the CSP. Required 
credentials can include zero or more certificates, zero or more caller names, and one or more 
samples. Traditionally a caller name has been used to establish the context of a login 
session. Certificates can be used for the same purpose. I f certificates and/or caller names are 
provided as input, these must be provided as immediate values in this structure. The 
samples can be provided as immediate values or can be obtained through a callback 
function included in the AccessCred structure. 


AclEdit (input) 


A structure containing information that defines the edit operation. Valid operations include 
adding, replacing, and deleting entries in an ACL managed by the service provider. The 
AclEdit parameter can contain information for anew ACL entry and a handle uniquely 
identifying an existing ACL entry. The information controls the edit operation as follows: 


Value of AclEdit.EditMode Use of AclEdit.NewE ntry and 
AclEdit.OldE ntryHandle 


CSSM_ACL_EDIT_MODE_ADD Adds a new ACL entry tothe set of ACL entries 
controlling login sessions with the CSP. Thenew ACL 
entry is created from the ACL entry prototype contained 
in NewEntry. OldEntryHandle is ignored for this 

EditMode. 


CSSM_ACL_EDIT_MODE_DELETE Deletes the ACL entry identified by oOldEntryHandle 
and associated with login sessions with the CSP. 
NewEnt ry is ignored for this EditMode. 
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Value of AclEdit.E ditMode Use of AclEdit.NewE ntry and 
AclEdit.OldE ntryHandle 


CSSM_ACL_EDIT.MODE_REPLACE _ Replaces theACL entry identified by oldEntryHandle 
and controlling login sessions with the CSP. The existing 
ACL is replaced based on the ACL entry prototype 
contained in the NewEnt ry. 


When replacing an existing ACL entry, the caller must replace all items in an ACL entry. 
The replacement prototype includes: 


e« Subject type and value- A CSSM_LIST structure containing a typed subject. The 
subject identifies the entity authorized by this ACL entry. 


¢ Delegation flag- A CSSM_BOOL value indicating whether the subject can delegate the 
permissions recorded in the authorization array. 


¢ Authorization array - A CSSM_AUTHORIZATIONGROUP structure defining the set of 
operations for which permission is granted to the subject. 


¢ Validity period - ACSSM_ACL_VALIDITY_PERIOD structure containing two 
elements, the start time and the stop time for which the ACL entry is valid. 


e ACL entry tag - A CSSM_STRING containing a user-defined value associated with the 
ACL entry. 


DESCRIPTION 


This function edits the stored ACL controlling login sessions for a Cryptographic Service Provider (CSP). The 
ACL is modified according to the edit mode and information provided in AclEdit. 


The caller must have a login session in process and must be authorized to modify the target ACL. Caller 
authentication and authorization to edit the ACL is determined based on the caller-provided AccessCred. 


The caller must be authorized to add, delete, or replace the ACL entries controlling login to the CSP. When 
adding or replacing an ACL entry, the service provider must reject the creation of duplicate ACL entries. 


When adding a new ACL entry toan ACL, the caller must provide a complete ACL entry prototype. All ACL 
entry items, except the ACL entry Subject, must be provided as an immediate value in AclEdit .NewEntry. 
The ACL entry Subject can be provided as an immediate value, from a verifier with a protected data path, 
from an external authentication or authorization service, or through a callback function specified in 
AclEdit .NewEntry.Callback. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


None specific to this call. 
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SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 
Functions: CSSM_CSP_Ge@LoginACLCSSM_CSP_Login, CSSM_CSP_Logout 


151 


CSSM_CSP_ChangeL oginOwner 
NAME 
CSSM_CSP_ChangeLoginOwner - Define a new login owner (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_CSP_ChangeLoginOwner 
(CSSM_CSP_HANDLE CSPHandle, 

const CSSM_ACCESS_ CREDENTIALS *AccessCred, 
const CSSM_ACL_OWNER_PROTOTYPE *NewOwner) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CSPHandle (input) 


The module handle that identifies the Cryptographic Service Provider to perform this 
operation. 


AccessCred (input) 


A pointer to the set of one or more credentials used to prove the caller is the current login 
owner. Required credentials can include zero or more certificates, zero or more caller names, 
and one or more samples. If certificates and/or caller names are provided as input, these 
must be provided as immediate values in this structure. The samples can be provided as 
immediate values or can be obtained through a callback function included in the 
AccessCred structure. 


NewOwner (Input) 
A CSSM_ACL_OWNER_PROTOTYPE defining the new login owner. 


DESCRIPTION 
This function takes a CSSM_ACL_OWNER_PROTOTYPE describing the new login owner. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


None specific to this call. 
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SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 


Functions: CSSM_CSP_Get LoginOwner 
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CSSM_CSP_CreateAsymmetricContext 


NAME 


CSSM_CSP_CreateAsymmetricContext - Create an asymmetric encryption cryptographic context 
(CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_CSP_CreateAsymmetricContext 
(CSSM_CSP_HANDLE CSPHandle, 

CSSM_ALGORITHMS AlgorithmID, 

const CSSM_ACCESS_ CREDENTIALS *AccessCred, 

const CSSM_KEY *Key, 
CSSM_PADDING Padding, 
CSSM_CC_HANDLE *NewContextHandle) 


LIBRARY 


Common Security Services Manager library (cdsa$Sincssm300_shr.exe) 


PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform this function. If a NULL handle is specified, CSSM returns an error. 


AlgorithmID (input) 
The algorithm identification number for the algorithm used for asymmetric encryption. 
AccessCred (input) 


A pointer to the set of one or more credentials required to unlock the private key. The 
credentials structure can contain an immediate value for the credential, such as a 
passphrase, or the caller can specify a callback function the CSP can use to obtain one or 
more credentials. Credentials can be required for encryption and decryption operations. 


Key (input) 


The key used for asymmetric encryption. The caller passes a pointer toa CSSM_KEY 
structure containing the key. When the context is used for a sign operation, 
AccessCredentials is required to access the private key used for signing. When the 
context is used for a verify operation, the public key is used to verify the signature When 
the context is used for a wrapkey operation, the public key can be used as the wrapping key. 
When the context is used for an unwrap operation, AccessCredentials is required to 
access the private key used to perform the unwrapping. 


Padding (input/optional) 

The method for padding. Typically specified for ciphers that pad. 
NewContextHandle (output) 

Cryptographic context handle. 
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DESCRIPTION 


This function creates an asymmetric encryption cryptographic context, given a handle of a CSP, an algorithm 
identification number, a key, and padding. The cryptographic context handle is returned. The cryptographic 
context handle can be used to call asymmetric encryption functions and cryptographic wrap or unwrap 
functions. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 


Functions: CSSM_DecryptData, CSSM_DecryptDatal nit, CSSM_DecryptDataU pdate 
CSSM_DecryptDataFinal, CSSM_DeeeContext, CSSM_EncryptData, CSSM_EncryptDatal nit, 
CSSM_EncryptDataU pdate, CSSM_EncryptDataFinal, CSSM_GetContextt, CSSM_GetContextAttribute 
CSSM_QuerySize, CSSM_SeContext, CSSM_UpdateContextAttri butes 
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CSSM_CSP_CreateDeriveKeyC ontext 
NAME 


CSSM_CSP_CreateDerivekK eyContext - Create a cryptographic context to derive a symmetric key 
(CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_CSP_CreateDeriveKeyContext 
(CSSM_CSP_HANDLE CSPHandle, 

CSSM_ALGORITHMS AlgorithmID, 

CSSM_KEY_TYPE DeriveKeyType, 

uint32 DeriveKeyLengthInBits, 

const CSSM_ACCESS_CREDENTIALS *AccessCred, 
const CSSM_KEY *BaseKey, 

uint32 IterationCount, 

const CSSM_DATA *Salt, 

const CSSM_CRYPTO_DATA *Seed, 


CSSM_CC_HANDLE *NewContextHandle) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform this function. If a NULL handleis specified, CSSM returns an error. 


AlgorithmID (input) 

The algorithm identification number for a derived key algorithm. 
DeriveKeyType (input) 

The type of symmetric key to derive. 
DeriveKeyLengthInBits (input) 

The logical length of the key in bits to be derived ( LogicalKeySizeInBits) 
AccessCred (input/optional) 


A pointer to the set of one or more credentials required to access the base key. The 
credentials structure can contain an immediate value for the credential, such as a 
passphrase, or the caller can specify a callback function the CSP can use to obtain one or 
more credentials. If the BaseKey is NULL, then this parameter is optional. 


BaseKey (input/optional) 


The base key used to derive the new key. The base key can be a public key, a private key, or 
a symmetric key 


IterationCount (input/optional) 
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The number of iterations to be performed during the derivation process. Used heavily by 
password-based derivation methods. 


Salt (input/optional) 
A Salt used in deriving the key. 
Seed (input/optional) 


A seed used to generate a random number. The caller can either pass a seed and seed length 
in bytes or pass a callback function. If Seed is NULL, the Cryptographic Service Provider 
will use its default seed-handling mechanism. 


NewContextHandle (output) 
Cryptographic context handle. 


DESCRIPTION 


This function creates a cryptographic context to derive a symmetric key, given a handle of a CSP, an 
algorithm, the type of symmetric key to derive, the length of the derived key, and an optional seed or an 
optional AccessCredentials structure from which to derive a new key. The cryptographic context handle is 
returned. The cryptographic context handle can be used for calling the cryptographic derive key function. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 


Functions: CSSM_DeriveKey 
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CSSM_CSP_CreateDigestC ontext 


NAME 
CSSM_CSP_CreateDigestContext - Create a digest cryptographic context (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_CSP_CreateDigestContext 
(CSSM_CSP_HANDLE CSPHandle, 

CSSM_ALGORITHMS AlgorithmID, 

CSSM_CC_HANDLE *NewContextHandle) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform this function. If a NULL handleis specified, CSSM returns error. 


AlgorithmID (input) 

The algorithm identification number for message digests. 
NewContextHandle (output) 

Cryptographic context handle. 


DESCRIPTION 


This function creates a digest cryptographic context, given a handle of a CSP and an algorithm identification 
number. The cryptographic context handle is returned. The cryptographic context handle can be used to call 
digest cryptographic functions. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 


Functions: CSSM_DigestData, CSSM_DigestDatal nit, CSSM_DigestDataUpdate, CSSM_DigestDataF inal, 
CSSM_GeContext, CSSM_SetContext, CSSM_DdeteContext, CSSM_GetContextAttribute 
CSSM_UpdateContextAttributes 
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CSSM_CSP_CreateKeyGenContext 
NAME 
CSSM_CSP_CreateK eyGenContext - Create a key generation cryptographic context (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_CSP_CreateKeyGenContext 
(CSSM_CSP_HANDLE CSPHandle, 

CSSM_ALGORITHMS AlgorithmID, 
uint32 KeySizeInBits, 

const CSSM_CRYPTO_DATA *Seed, 
const CSSM_DATA *Salt, 

const CSSM_DATE *StartDate, 

const CSSM_DATE *EndDate, 

const CSSM_DATA *Params, 
CSSM_CC_HANDLE *NewContextHandle) 


LIBRARY 


Common Security Services Manager library (cdsa$Sincssm300_shr.exe) 


PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform this function. If a NULL handle is specified, CSSM returns an error. 


AlgorithmID (input) 
The algorithm identification number of the algorithm used for key generation. 
KeySizeInBits (input) 


The logical size of the key (specified in bits). This refers to either the actual key size (for 
symmetric key generation) or the modulus size (for asymmetric key pair generation). 


Seed (input/optional) 


A seed used to generate the key. The caller can either pass a seed and seed length in bytes or 
pass a callback function. If NULL is passed, the Cryptographic Service Provider will use its 
default seed-handling mechanism. 


Salt (input/optional) 
A salt used to generate the key. 
StartDate (input/optional) 
A start date for the validity period of the key or key pair being generated. 


EndDate (input/optional) 


An end date for the validity period of the key or key pair being generated. 
Params (input/optional) 


A data buffer containing parameters required to generate a key pair for a specific algorithm. 
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NewContextHandle (output) 


Cryptographic context handle. 


DESCRIPTION 


This function creates a key generation cryptographic context, given a handle of a CSP, an algorithm 
identification number, a passphrase, a modulus size (for public or private keypair generation), a key size (for 
symmetric key generation), a seed, and a salt. The cryptographic context handle is returned. The 
cryptographic context handle can be used to call key/ or keypair generation functions. 


Additional attributes can be added to the newly created context using the 

CSSM_UpdateContextAttributes () function. Incremental attributes of interest for key generation includea 
handle-pair identifying a Data Storage Library service module and an open data store for CSPs that manage 
multiple persistent key stores. If a CSP does not support multiple key stores, the CSP ignores the presence or 
absence of this attribute. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


SEE ALSO 


Books 
Inta CDSA Application Devdoper's Guide 
Online Help 


Functions: CSSM_Generat&Key, CSSM_GenerateKeyPair, CSSM_GeContext, CSSM_SetContext, 
CSSM_DdeteContext, CSSM_GetContextAttribute CSSM_UpdateContextAttri butes 
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CSSM_CSP_CreateMacContext 
NAME 


CSSM_CSP_CreateMacContext - Create a message authentication code cryptographic context 
(CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_CSP_CreateMacContext 
(CSSM_CSP_HANDLE CSPHandle, 

CSSM_ALGORITHMS AlgorithmID, 

const CSSM_KEY *Key, 

CSSM_CC_HANDLE *NewContextHandle) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform this function. If a NULL handleis specified, CSSM returns error. 


AlgorithmID (input) 
The algorithm identification number for the MAC algorithm. 
Key (input) 


The key used to generate a message authentication code. Caller passes a pointer toa 
CSSM_KEY structure containing the key. 


NewContextHandle (output) 
Cryptographic context handle. 


DESCRIPTION 


This function creates a message authentication code cryptographic context, given a handle of a CSP, 
algorithm identification number, and a key. The cryptographic context handle is returned. The cryptographic 
context handle can be used to call message authentication code functions. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


161 


Online Help 


Functions: CSSM_GenerateMac, CSSM_GeerateMacl nit, CSSM_GenerateMacU pdate 
CSSM_GenerateMacFinal, CSSM_VerifyMac, CSSM_ VerifyMacinit, CSSM_VerifyMacU pdate 
CSSM_VerifyMacFinal, CSSM_Ge&Context, CSSM_SeContext, CSSM_DdeteContett, 
CSSM_GeContextAttribute, CSSM_UpdateContextAttri butes 
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CSSM_CSP_CreatePassThroughC ontext 
NAME 

CSSM_CSP_CreatePassT hroughContext - Create a custom cryptographic context (CDSA) 
SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_CSP_CreatePassThroughContext 
(CSSM_CSP_HANDLE CSPHandle, 

const CSSM_KEY *Key, 

CSSM_CC_HANDLE *NewContextHandle) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform this function. If a NULL handleis specified, CSSM returns an error. 


Key (input) 


The key to be used for the context. The caller passes a pointer toa CSSM_KEY structure 
containing the key. 


NewContextHandle (output) 
Cryptographic context handle. 


DESCRIPTION 


This function creates a custom cryptographic context, given a handle of a CSP and a pointer toa custom input 
data structure. The cryptographic context handle is returned. The cryptographic context handle can be used 
to call the CSSM pass-through function for the CSP. 


NOTES 


A CSP can create its own set of custom functions. The context information can be passed through its own data 
structure. The CSSM_CSP_PassThrough () function should be used with the function ID to call the desired 
custom function. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 
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SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 


Functions: CSSM_CSP_PassThroughCSSM_GetContext, CSSM_Sda&Context, CSSM_ DdeteContett, 
CSSM_GeContextAttribute CSSM_ UpdateContextAttri butes 
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CSSM_CSP_CreateDeriveKeyC ontext 
NAME 


CSSM_CSP_CreateDerivekK eyContext - Create a cryptographic context to derive a symmetric key 
(CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_CSP_CreateDeriveKeyContext 
(CSSM_CSP_HANDLE CSPHandle, 

CSSM_ALGORITHMS AlgorithmID, 

CSSM_KEY_TYPE DeriveKeyType, 

uint32 DeriveKeyLengthInBits, 

const CSSM_ACCESS_CREDENTIALS *AccessCred, 
const CSSM_KEY *BaseKey, 

uint32 IterationCount, 

const CSSM_DATA *Salt, 

const CSSM_CRYPTO_DATA *Seed, 


CSSM_CC_HANDLE *NewContextHandle) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform this function. If a NULL handleis specified, CSSM returns an error. 


AlgorithmID (input) 

The algorithm identification number for a derived key algorithm. 
DeriveKeyType (input) 

The type of symmetric key to derive. 


DeriveKeyLengthInBits (input) 


The logical length of the key in bits to be derived (LogicalKeySizeInBits) 
AccessCred (input/optional) 


A pointer to the set of one or more credentials required to access the base key. The 
credentials structure can contain an immediate value for the credential, such as a 
passphrase, or the caller can specify a callback function the CSP can use to obtain one or 
more credentials. If the BaseKey is NULL, then this parameter is optional. 


BaseKey (input/optional) 


The base key used to derive the new key. The base key can be a public key, a private key, or 
a symmetric key 


IterationCount (input/optional) 
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The number of iterations to be performed during the derivation process. Used heavily by 
password-based derivation methods. 


Salt (input/optional) 
A Salt used in deriving the key. 
Seed (input/optional) 


A seed used to generate a random number. The caller can either pass a seed and seed length 
in bytes or pass a callback function. If Seed is NULL, the Cryptographic Service Provider 
will use its default seed-handling mechanism. 


NewContextHandle (output) 
Cryptographic context handle. 


DESCRIPTION 


This function creates a cryptographic context to derive a symmetric key, given a handle of a CSP, an 
algorithm, the type of symmetric key to derive, the length of the derived key, and an optional seed or an 
optional AccessCredentials structure from which to derive a new key. The cryptographic context handle is 
returned. The cryptographic context handle can be used for calling the cryptographic derive key function. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 


Functions: CSSM_DeriveKey 
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CSSM_CSP_CreateDigestC ontext 


NAME 
CSSM_CSP_CreateDigestContext - Create a digest cryptographic context (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_CSP_CreateDigestContext 
(CSSM_CSP_HANDLE CSPHandle, 

CSSM_ALGORITHMS AlgorithmID, 

CSSM_CC_HANDLE *NewContextHandle) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform this function. If a NULL handleis specified, CSSM returns error. 


AlgorithmID (input) 

The algorithm identification number for message digests. 
NewContextHandle (output) 

Cryptographic context handle. 


DESCRIPTION 


This function creates a digest cryptographic context, given a handle of a CSP and an algorithm identification 
number. The cryptographic context handle is returned. The cryptographic context handle can be used to call 
digest cryptographic functions. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 


Functions: CSSM_DigestData, CSSM_DigestDatal nit, CSSM_DigestDataUpdate, CSSM_DigestDataF inal, 
CSSM_GeContext, CSSM_SetContext, CSSM_DdeteContext, CSSM_GetContextAttribute 
CSSM_UpdateContextAttributes 
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CSSM_CSP_CreateKeyGenContext 
NAME 
CSSM_CSP_CreateK eyGenContext - Create a key generation cryptographic context (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_CSP_CreateKeyGenContext 
(CSSM_CSP_HANDLE CSPHandle, 

CSSM_ALGORITHMS AlgorithmID, 
uint32 KeySizeInBits, 

const CSSM_CRYPTO_DATA *Seed, 
const CSSM_DATA *Salt, 

const CSSM_DATE *StartDate, 

const CSSM_DATE *EndDate, 

const CSSM_DATA *Params, 
CSSM_CC_HANDLE *NewContextHandle) 


LIBRARY 


Common Security Services Manager library (cdsa$Sincssm300_shr.exe) 


PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform this function. If a NULL handle is specified, CSSM returns an error. 


AlgorithmID (input) 
The algorithm identification number of the algorithm used for key generation. 
KeySizeInBits (input) 


The logical size of the key (specified in bits). This refers to either the actual key size (for 
symmetric key generation) or the modulus size (for asymmetric key pair generation). 


Seed (input/optional) 


A seed used to generate the key. The caller can either pass a seed and seed length in bytes or 
pass a callback function. If NULL is passed, the Cryptographic Service Provider will use its 
default seed-handling mechanism. 


Salt (input/optional) 
A salt used to generate the key. 
StartDate (input/optional) 
A start date for the validity period of the key or key pair being generated. 


EndDate (input/optional) 


An end date for the validity period of the key or key pair being generated. 
Params (input/optional) 


A data buffer containing parameters required to generate a key pair for a specific algorithm. 
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NewContextHandle (output) 
Cryptographic context handle. 


DESCRIPTION 


This function creates a key generation cryptographic context, given a handle of a CSP, an algorithm 
identification number, a passphrase, a modulus size (for public or private keypair generation), a key size (for 
symmetric key generation), a seed, and a salt. The cryptographic context handle is returned. The 
cryptographic context handle can be used to call key/ or keypair generation functions. 


Additional attributes can be added to the newly created context using the 

CSSM_UpdateContextAttributes () function. Incremental attributes of interest for key generation includea 
handle-pair identifying a Data Storage Library service module and an open data store for CSPs that manage 
multiple persistent key stores. If a CSP does not support multiple key stores, the CSP ignores the presence or 
absence of this attribute. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 


Functions: CSSM_Generat&Key, CSSM_GenerateKeyPair, CSSM_GeContext, CSSM_SetContext, 
CSSM_DdeteContext, CSSM_GetContextAttribute CSSM_UpdateContextAttri butes 
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CSSM_CSP_CreateMacContext 
NAME 


CSSM_CSP_CreateMacContext - Create a message authentication code cryptographic context 
(CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_CSP_CreateMacContext 
(CSSM_CSP_HANDLE CSPHandle, 

CSSM_ALGORITHMS AlgorithmID, 

const CSSM_KEY *Key, 

CSSM_CC_HANDLE *NewContextHandle) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform this function. If a NULL handleis specified, CSSM returns error. 


AlgorithmID (input) 
The algorithm identification number for the MAC algorithm. 
Key (input) 


The key used to generate a message authentication code. Caller passes a pointer toa 
CSSM_KEY structure containing the key. 


NewContextHandle (output) 
Cryptographic context handle. 


DESCRIPTION 


This function creates a message authentication code cryptographic context, given a handle of a CSP, 
algorithm identification number, and a key. The cryptographic context handle is returned. The cryptographic 
context handle can be used to call message authentication code functions. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 
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Online Help 


Functions: CSSM_GeerateVMac, CSSM_GeerateMacl nit, CSSM_GenerateMacU pdate 
CSSM_GenerateMacFinal, CSSM_VerifyMac, CSSM_ VerifyMacinit, CSSM_VerifyMacU pdate 
CSSM_VerifyMacFinal, CSSM_Ge&Context, CSSM_ SeContext, CSSM_DdeteContett, 
CSSM_GeContextAttribute, CSSM_UpdateContextAttri butes 
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CSSM_CSP_CreatePassThroughC ontext 
NAME 
CSSM_CSP_CreatePassT hroughContext - Create a custom cryptographic context (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_CSP_CreatePassThroughContext 
(CSSM_CSP_HANDLE CSPHandle, 

const CSSM_KEY *Key, 

CSSM_CC_HANDLE *NewContextHandle) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform this function. If a NULL handleis specified, CSSM returns an error. 


Key (input) 


The key to be used for the context. The caller passes a pointer toa CSSM_KEY structure 
containing the key. 


NewContextHandle (output) 
Cryptographic context handle. 


DESCRIPTION 


This function creates a custom cryptographic context, given a handle of a CSP and a pointer toa custom input 
data structure. The cryptographic context handle is returned. The cryptographic context handle can be used 
to call the CSSM pass-through function for the CSP. 


NOTES 


A CSP can create its own set of custom functions. The context information can be passed through its own data 
structure. The CSSM_CSP_PassThrough () function should be used with the function ID to call the desired 
custom function. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 
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SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 


Functions: CSSM_CSP_PassThroughCSSM_GetContext, CSSM_Sda&Context, CSSM_ DdeteContett, 
CSSM_GeContextAttribute CSSM_ UpdateContextAttri butes 
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CSSM_CSP_CreateRandomGenContext 
NAME 


CSSM_CSP_CreateRandomGenContext - Create a random number generation cryptographic 
context (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_CSP_CreateRandomGenContext 
(CSSM_CSP_HANDLE CSPHandle, 

CSSM_ALGORITHMS AlgorithmID, 

const CSSM_CRYPTO_DATA *Seed, 

uint32 Length, 
CSSM_CC_HANDLE *NewContextHandle) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform this function. If a NULL handleis specified, CSSM returns AN error. 


AlgorithmID (input) 
The algorithm identification number for random number generation. 
Seed (input/optional) 


A seed used to generate THE random number. The caller can either pass a seed and seed 
length in bytes or pass a callback function. If NULL is passed, the Cryptographic Service 
Provider will use its default seed-handling mechanism. 


Length (input) 

The length of the random number to be generated. 
NewContextHandle (output) 

Cryptographic context handle. 


DESCRIPTION 


This function creates a random number generation cryptographic context, given a handle of a CSP, an 
algorithm identification number, a seed, and the length of the random number in bytes. The cryptographic 
context handle is returned and can be used for the random number generation function. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 
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SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 


Functions: CSSM_GeerateRandom, CSSM_GeContext, CSSM_SetContext, CSSM_ DedeteContett, 
CSSM_GeContextAttribute CSSM_UpdateContextAttri butes 
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CSSM_CSP _CreateSignatureContext 


NAME 
CSSM_CSP_CreateSignatureContext - Create a signature cryptographic context (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_CSP_CreateSignatureContext 
(CSSM_CSP_HANDLE CSPHandle, 

CSSM_ALGORITHMS AlgorithmID, 

const CSSM_ACCESS_ CREDENTIALS *AccessCred, 

const CSSM_KEY *Key, 
CSSM_CC_HANDLE *NewContextHandle) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform this function. If a NULL handleis specified, CSSM returns error. 


AlgorithmID (input) 
The algorithm identification number for a signature/verification algorithm. 
AccessCred (input/optional) 


A pointer to the set of one or more credentials required to unlock the private key. The 
credentials structure can contain an immediate value for the credential, such as a 
passphrase, or the caller can specify a callback function the CSP can use to obtain one or 
more credentials. Credentials are required for signature operations, not for verify 
operations. 


Key (input) 


The key used to sign and verify. The caller passes a pointer toa CSSM_KEY structure 
containing the key and the key length. 


NewContextHandle (output) 
Cryptographic context handle. 


DESCRIPTION 


This function creates a signature cryptographic context for sign and verify, given a handle of a CSP, an 
algorithm identification number, a key, and an AccessCredentials structure. The AccessCredentials 
structure will be used to unlock the private key when this context is used to perform a signing operation. The 
cryptographic context handle is returned. The cryptographic context handle can be used to call sign and verify 
cryptographic functions. 
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RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 


Functions: CSSM_SignData, CSSM_SignDatal nit, CSSM_SignDataU pdate, CSSM_SignDataFinal, 
CSSM_VerifyData, CSSM_VerifyDatal nit, CSSM_VerifyDataUpdate, CSSM_VerifyDataFinal, 
CSSM_Ge&Context, CSSM_SetContext, CSSM_DedeteContext, CSSM_GetContextAttri bute 
CSSM_UpdateContextAttributes 
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CSSM_CSP_CreateSymmetricC ontext 
NAME 


CSSM_CSP_CreateSymmetricContext - Create a symmetric encryption cryptographic context 
(CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_CSP_CreateSymmetricContext 
(CSSM_CSP_HANDLE CSPHandle, 
CSSM_ALGORITHMS AlgorithmID, 


CSSM_ENCRYPT_MODE Mode, 
const CSSM_ACCESS_ CREDENTIALS *AccessCred, 
const CSSM_KEY *Key, 
const CSSM_DATA *InitVector, 
CSSM_PADDING Padding, 

void *Reserved, 

CSSM_CC_HANDLE *NewContextHandle) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform this function. If a NULL handleis specified, CSSM returns error. 


AlgorithmID (input) 

The algorithm identification number for symmetric encryption. 
Mode (input) 

The mode of the specified algorithm | D. 
AccessCred (input/optional) 


A pointer to the set of one or more credentials required to unlock the private key. The 
credentials structure can contain an immediate value for the credential, such as a 
passphrase, or the caller can specify a callback function the CSP can use to obtain one or 
more credentials. Credentials may be required for encryption, decryption, and wrapping 
operations. 


Key (input) 


The Key used for symmetric encryption. The caller passes a pointer toa CSSM_KEY 
structure containing the key. 


InitVector (input/optional) 

The initial vector for symmetric encryption. This is typically specified for block ciphers. 
Padding (input/optional) 

The method for padding. This is typically specified for ciphers that pad. 
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Reserved (input) 

Reserved for future use. 
NewContextHandle (output) 

Cryptographic context handle. 


DESCRIPTION 


This function creates a symmetric encryption cryptographic context, given a handle of a CSP, an algorithm 
identification number, a key, an initial vector, padding, and the number of encryption rounds. 
Algorithm-specific attributes must be added to the context after the initial creation using the 
CSSM_UpdateContextAttributes () function. The cryptographic context handle is returned. The 
cryptographic context handle can be used to call symmetric encryption functions and the cryptographic wrap 
or unwrap functions. 


Additional attributes can be added to the newly created context using the 

CSSM_UpdateContextAttributes () function . |ncremental attributes of interest when using this context to 

unwrap a key includea handle-pair identifying a Data Storage Library service module and an open data store 
for CSPs that manage multiple, persistent key stores. If a CSP does not support multiple key stores, the CSP 
ignores the presence or absence of this attribute. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 


Functions: CSSM_DecryptData, CSSM_DecryptDatal nit, CSSM_DecryptDataU pdate 
CSSM_DecryptDataFinal, CSSM_ DeeeContext, CSSM_EncryptData, CSSM_EncryptDatal nit, 
CSSM_EncryptDataU pdate, CSSM_EncryptDataFinal, CSSM_GetContextt, CSSM_GetContextAttribute 
CSSM_QuerySize, CSSM_SeContext, CSSM_UpdateContextAttri butes 
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CSSM_CSP_GetLoginAcl 


NAME 
CSSM_CSP_GetLoginAcl - Get description of CSP ACL entries (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_CSP_GetLoginAcl 
(CSSM_CSP_HANDLE CSPHandle, 
const CSSM_STRING *SelectionTag, 
uint32 *NumberOfAclInfos, 


CSSM_ACL_ENTRY_INFO_PTR *AcliInfos) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CSPHandle (input) 


The module handle that identifies the Cryptographic Service Provider to perform this 
operation. 


Select ionTag (input/optional) 


A CSSM_STRING value matching the user-defined tag value associated with one or more 
ACL entries controlling login sessions. To retrieve a description of all ACL entries 
controlling login sessions, this parameter must be NULL. 


NumberOfAclInfos (output) 


The number of entries in the AclInfos array. If no ACL entry descriptions are returned, 
this value is zero. 


AcliInfos (output) 


An array of CSSM_ACL_ENTRY_INFO structures. The unique handle contained in this 
structure can be used during the current attach session and the current login session to 
reference specific ACL entries for editing. The structure is allocated by the service provider 
and must be released by the caller when the structure is no longer needed. If no ACL entry 
descriptions are returned, this value is NULL. 


DESCRIPTION 


This function returns a description of zero or more ACL entries managed by the CSP and used to control login 
sessions with the CSP. The optional input SelectionTag parameter restricts the returned descriptions to 
those ACL entries with a matching EntryTag value. If a SelectionTag value is specified and no matches are 
found, zero descriptions are returned. If no SelectionTag is specified, a description of all ACL entries used to 
control login sessions are returned by this function. 


Each Aclinfo structure contains: 


e Public contents of an ACL entry 


e ACL EntryHandle, which is a unique value defined and managed by the service provider 
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The public ACL entry information returned by this function includes: 


e« Subject type — A CSSM_LIST structure containing one element identifying the type of subject stored in 
the ACL entry. 


¢ Delegation flag — A CSSM_BOOL value indicating whether the subject can delegate the permissions 
recorded in the authorization array. 


e Authorization array — A CSSM_AUTHORIZATIONGROUP structure defining the set of operations for 
which permission is granted to the subject. 


¢ Validity period — A CSSM_ACL_VALIDITY_PERIOD structure containing two elements, the start time 
and the stop time for which the ACL entry is valid. 


e ACL entry tag— A CSSM_STRING containing a user-defined value associated with the ACL entry. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


None specific to this call. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 
Functions: CSSM_CSP_Login, CSSM_CSP_LoginAclICSSM_CSP_Logout 
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CSSM_CSP_GetLoginOwner 


NAME 
CSSM_CSP_GetLoginOwner - Get login owner data (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_CSP_GetLoginOwner 
(CSSM_CSP_HANDLE CSPHandle, 
CSSM_ACL_OWNER_PROTOTYPE_PTR Owner) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CSPHandle (input) 


The module handle that identifies the Cryptographic Service Provider to perform this 
operation. 


Owner (output) 
A CSSM_ACL_OWNER_PROTOTYPE describing the login owner. 


DESCRIPTION 
This function returns a CSSM_ACL_OWNER_PROTOTYPE describing the current login owner of the CSP. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


None specific to this call. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 
Functions: CSSM_CSP_ChangeLoginOwner 
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CSSM_CSP Login 
NAME 

CSSM_CSP_Login - Log user in tothe CSP (CDSA) 
SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_CSP_Login 
(CSSM_CSP_HANDLE CSPHandle, 

const CSSM_ACCESS_ CREDENTIALS *AccessCred, 
const CSSM_DATA *LoginName, 

const void *Reserved) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CSPHandle (input) 
Handle of the CSP to log in to. 
AccessCred (input) 


A pointer to the set of one or more credentials required to log in to the token or 
Cryptographic Service Provider. The credentials structure can contain an immediate value 
for the credential, such as a passphrase or PIN, or the caller can specify a callback function 
the CSP can use to obtain one or more credentials. 


LoginName (input/optional) 


A name or ID of the caller. The value is used with the provided AccessCred to authenticate 
and authorize the caller for login with the CSP. The CSP can require that a name value be 

provided. If a name value is not provided, the CSP can assume a default name under which 
to perform the authentication and authorization check, or the login request can fail. 


Reserved (input) 


This field is reserved for future use. The value NULL should always be given. (May be used 
for multiple user support in the future.) 


DESCRIPTION 
Logs the user in tothe CSP, allowing for multiple login types. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 
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CSSMERR_CSP_INVALID_LOGIN_NAME 
CSSMERR_CSP_ALREADY_LOGGED_IN 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 
Functions: CSSM_CSP_GeLoginAdl, CSSM_CSP_ChangeLoginAcl, CSSM_CSP_Logout 
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CSSM_CSP_Logout 
NAME 


CSSM_CSP_Logout - Terminate the login session (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RI 


(CSSM_CSP_HANDLE 


ETURN CSS 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


IAPI CSSM_CSP_Logout 
CSPHandle) 


PARAMETERS 


CSPHandle (input) 


Handle for the target CSP. 


DESCRIPTION 


Terminates the login session associated with the specified CSP handle 


RETURN VALUE 
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 


indicates success. All other values represent an error condition. 


ERR 


Errors are described in the CDSA Technical Standard. 


ORS 


None specific to this call. 


SEE 


Books 


Inta CDSA Application Devdoper's Guide 


Online 


Functions: CSSM_CSP_Login, CSSM_CSP_GetLoginAcl, CSSM_CSP_ChangeLoginAd 


ALSO 


Help 
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CSSM_DeleteContext 


NAME 
CSSM_DeleteContext - Free the context structure (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_DeleteContext 
(CSSM_CC_HANDLE CCHandle) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CCHandle (input) 
The handle that describes a context to be deleted. 


DESCRIPTION 


This function frees the context structure allocated by any of the cCSSM_Createxxxxx context functions. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CSSM_INVALID_CONTEXT_HANDLE 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 


Functions: CSSM_CSP_CreateAsymmetricContext, CSSM_CSP_CreatekeyGenContett, 
CSSM_CSP_CreateDigestContext, CSSM_CSP_CreateSignatureContett, 
CSSM_CSP_CreateSymmetricContext, and others. 
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CSSM_DeleteContextAttributes 


NAME 
CSSM_DeleteContextAttributes - Delete internal data (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_DeleteContextAttributes 
(CSSM_CC_HANDLE CCHandle, 
uint32 NumberOfAttributes, 
const CSSM_CONTEXT_ATTRIBUTE *ContextAttributes) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 
CCHandle (input) 
The handle that describes a context that is to be deleted. 
NumberOfAttributes (input) 
The number of attributes to be deleted as specified in the array of context attributes. 
ContextAttributes (input) 


The attributes to be deleted from the context. Only the attribute type is required. Any 
attribute values in the CSSM_CONTEXT_ATTRIBUTE structures are ignored. 


DESCRIPTION 


This function deletes internal data associated with the given attribute type of the context handle. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CSSM_INVALID_CONTEXT_HANDLE 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 
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Online Help 
Functions: CSSM_GetContextAttributes, CSSM_UpdateContextAttri butes 
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cssm_DeregisterManager Services 
NAME 
cssm_DeregisterM anagerServices - Deregister manager services 


SYNOPSIS 


#include <cssm.h> 


void CSSMAPI cssm_DeregisterManagerServices 
(const CSSM_GUID *Guid); 


PARAMETERS 


GUID (input) 


A pointer tothe CSSM_GUID structure containing the global unique identifier for this 
module. 


DESCRIPTION 


This function is used by an elective module manager to deregister its function table with CSSM core services 
prior to termination. This function is invoked by an elective module manager only when exiting due to an 
error condition detected by the EMM. This allows CSSM to clean up any state information associated with the 
exitingEMM. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 
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CSSM_FreeContext 


NAME 
CSSM_FreeContext - Free memory associated with the context structure (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_FreeContext 
(CSSM_CONTEXT_PTR Context) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


Context (input) 


The pointer to the memory that describes the context structure. 


DESCRIPTION 


This function frees the memory associated with the context structure. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


None specific to this call. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 
Functions: CSSM_GetContext 
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CSSM_GetAPIMemoryF unctions 
NAME 


CSSM_GetAPI MemoryF unctions - Retrieve the memory function table associated with the security 
service module 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_GetAPIMemoryFunctions 
(CSSM_MODULE_HANDLE AddInHandle, 
CSSM_API_MEMORY_FUNCS_PTR AppMemoryFuncs) 


LIBRARY 


Common Security Services Manager library (cdsa$Sincssm300_shr.exe) 


PARAMETERS 


AddInHandle (input) 


The handle to the security service module that is associated with the requested memory 
function table. 


AppMemoryFuncs (output) 


The pointer to an empty memory functions table. Upon function return, the table is filled 
with the memory function pointers associated with the specified attach handle. Caller has to 
allocate the buffer. 


DESCRIPTION 


This function retrieves the memory function table associated with the security service module identified by 
the input handle 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


SEE ALSO 
Inta CDSA Application Devdoper's Guide 
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cssm_GetAppMemoryF unctions 
NAME 
cssm_GetAppM emoryF unctions - Get service functions (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI cssm_GetAppMemoryFunctions 
(CSSM_MODULE_HANDLE hAddIn, 
CSSM_UPCALLS_PTR UpcallTable) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


hAddIn (input) 


The handle identifying the attach-session whose memory management function table is 
returned by this function. 


UpcallTable (output) 


The table containing sets of service functions among them a set of four memory 
management functions provided by the application that initiated the attach-session 
identified by hAddIn. 


DESCRIPTION 


This function gets a function table containing sets of service functions. Among these service functions are four 
application-provided memory management functions. The elective module manager can use these functions to 
manage memory on behalf of the application. The returned function table is specific to the attach-session 
identified by the module handle. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 
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cssm_GetAttachF unctions 


NAME 
cssm_GetAttachF unctions - Get SPI function table (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI cssm_GetAttachFunctions 
(CSSM_MODULE_HANDLE hAddIn, 
CSSM_SERVICE_MASK AddinType, 

void **SPFunctions, 

CSSM_GUID_PTR Guid) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 
hAddIn (input) 


The handle identifying the attach-session whose function table is to be returned by this 
function. 


AddinType (input) 


A CSSM_SERVICE_MASK value identifying the type of service module whose function 
table is to be returned by this function. 


SPFunctions (output) 


A pointer to the service module function table, which CSSM acquired from the service 
module during module-attach processing. The module manager should use this table to 


forward application invocation of the elective APIs to their corresponding SPIs. The memory 


pointed to by the function pointers should not be freed by the EMM. 


Guid (output) 


A CSSM_GUID value identifying the service module whose function table is to be returned 


by this function. 


DESCRIPTION 


This function returns an SPI function table for the service module identified by the module handle. The 


module must be of the type specified by the service mask. The SPFunctions parameter contains the returned 
function table. The elective module manager must use this function table to forward an application's call to 
the elective APIs to their corresponding SPIs represented in the function table. The returned Guid identifies 


the service module. It can be used to locate credentials and other information about the service module. 


This function sets a lock on the SP functions table. The CSSM service function 
cssm_ReleaseAttachFunctions () must be used to release the lock. 
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RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 
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CSSM_GetContext 


NAME 
CSSM_GetContext - Get context information (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_GetContext 
(CSSM_CC_HANDLE CCHandle, 
CSSM_CONTEXT_PTR *Context) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 
CCHandle (input) 

The handle to the context information. 
Context (output) 


The pointer to the CSSM_CONTEXT_PTR structure that describes the context associated 
with the ccHandle handle The pointer will be set to NULL if the function fails. Use 
CSSM_FreeContext () to free the memory allocated by the CSSM. 


DESCRIPTION 


This function retrieves the context information when provided with a context handle. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CSSM_INVALID_CONTEXT_HANDLE 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 
Functions: CSSM_FreeContext, CSSM_SetContext 
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CSSM_GetContextAttribute 


NAME 
CSSM_GetContextAttribute - Get context attribute (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_GetContextAttribute 
(const CSSM_CONTEXT *Context, 

uint32 AttributeType, 
CSSM_CONTEXT_ATTRIBUTE_PTR *ContextAttribute) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


Context (input) 

A pointer to the context. 
AttributeType (input) 

The attribute type of the desired attribute value. 
ContextAttribute (output) 


The pointer to the CSSM_CONTEXT_ATTRIBUTE that describes the context attributes 
associated with the ccHandle handle and the attribute type. The pointer will be set to 
NULL if the function fails. Call cSSM_DeleteContextAttributes () to free memory 
allocated by the CSSM. 


DESCRIPTION 


This function returns the value of a context attribute. Context references the cryptographic context to be 
searched for the attribute specified by Att ributeType. If the specified attribute is not present, then aNULL 
pointer is returned. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CSSM_ATTRIBUTE_NOT_IN_CONTEXT 
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SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 
Functions: CSSM_DeleteContextAttributes, CSSM_GetContext 
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CSSM_GetKeyAcl 


NAME 
CSSM_GetKeyAcl - Get ACL entries by key (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_GetKeyAcl 
(CSSM_CSP_HANDLE CSPHandle, 

const CSSM_KEY *Key, 

const CSSM_STRING *SelectionTag, 
uint32 *NumberOfAclInfos, 
CSSM_ACL_ENTRY_INFO_PTR *AclInfos) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CSPHandle (input) 


The module handle that identifies the Cryptographic Service Provider to perform this 
operation. 


Key (input) 
A pointer to the target key whose associated ACL entries are scanned and returned. 
Select ionTag (input/optional) 


A CSSM_STRING value matching the user-defined tag value associated with one or more 
ACL entries for the target K ey. To retrieve a description of all ACL entries for the target 
Key, this parameter must be NULL. 


NumberOfAclInfos (output) 


The number of entries in the AclInfos array. If no ACL entry descriptions are returned, 
this value is zero. 


AcliInfos (output) 


An array of CSSM_ACL_ENTRY_INFO structures. The unique handle contained in this 
structure can be used during the current attach session to reference specific ACL entries for 
editing. The structureis allocated by the service provider and must be released by the caller 
when the structure is no longer needed. If no ACL entry descriptions are returned, this 
value is NULL. 


DESCRIPTION 


This function returns a description of zero or more ACL entries managed by the CSP and associated with the 
target key. The optional input SelectionTag restricts the returned descriptions to those ACL entries with a 
matching EntryTag value. If a SelectionTag value is specified and no matches are found, zero descriptions 
are returned. If no SelectionTag is specified, a description of all ACL entries associated with the key is 
returned by this function. 
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Each Aclinfo structure contains: 


e Public contents of an ACL entry 


¢ ACL EntryHandle, which is a unique value defined and managed by the service provider 
The public ACL entry information returned by this function includes: 
Subject type and value 


A CSSM_LIST structure containing one element identifying the type of subject stored in the 
ACL entry. 


Delegation flag 


A CSSM_BOOL value indicating whether the subject can delegate the permissions recorded 
in the authorization array. 


Authorization array 


A CSSM_AUTHORIZATIONGROUP structure defining the set of operations for which 
permission is granted to the subject. 


Validity period 


A CSSM_ACL_VALIDITY_PERIOD structure containing two elements, the start time and 
the stop time for which the ACL entry is valid. 


ACL entry tag 
A CSSM_STRING containing a user-defined value associated with the ACL entry. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


None specific to this call. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 
Functions: CSSM_ChangekeyAd 
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CSSM_GetKeyOwner 
NAME 
CSSM_GetK eyOwner - Get data describing key owner (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_GetKeyOwner 
(CSSM_CSP_HANDLE CSPHandle, 

const CSSM_KEY *Key, 
CSSM_ACL_OWNER_PROTOTYPE_PTR Owner) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CSPHandle (input) 


The module handle that identifies the Cryptographic service provider to perform this 
operation. 


Key (input) 
A pointer to the target key whose associated Owner is returned. 


Owner (output) 
A CSSM_ACL_OWNER_PROTOTYPE describing the current Owner of the Key. 


DESCRIPTION 
This function returns aCSSM_ACL_OWNER_PROTOTYPE describing the current Owner of the Key. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


None specific to this call. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 
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Online Help 
Functions: CSSM_ChangekeyOwner 
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CSSM_GetModuleGUIDFromHandle 


NAME 
CSSM_GetModuleGUIDFromHandle - Get GUID of the attached module (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_GetModuleGUIDFromHandle 
(CSSM_MODULE_HANDLE ModuleHandle, 
CSSM_GUID_PTR ModuleGUID) 


PARAMETERS 
ModuleHandle (input) 
The handle of the module for which the GUID should be returned. 


ModuleGUID (output) 


The GUID of the module associated with ModuleHandle.n. 


DESCRIPTION 
This function returns the GUID of the attached module identified by the specified handle. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 
Functions: CSSM_GetSubserviceUIDFromHandle 
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cssm_GetModulel nfo 
NAME 


cssm_GetModulel nfo - Get the module handle state information 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI cssm_GetModuleInfo 
(CSS ODULE_HANDLE Module, 
CSSM_GUID_PTR Guid, 

CSSM_VERSION_PTR Version, 

uint *SubServiceld, 
CSSM_SERVICE_TYPE *SubServiceType, 
CSSM_ATTACH_FLAGS *AttachFlags, 
CSSM_KEY_HIERARCHY *KeyHierarchy, 
CSSM_API_MEMORY_FUNCS_PTR AttachedMemFuncs, 
CSSM_FUNC_NAME_ADDR_PTR FunctionTable, 
uint32 NumFunctionTable); 
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PARAMETERS 


Module (input) 
The handle to a service provider module. 
GUID (input) 


A pointer tothe CSSM_GUID structure containing the global unique identifier for this 
module. 


Version (output) 

The version number set on ModuleAttach. 
SubServiceld (output) 

The slot number of the reader to which the module is attached. 
SubServiceType (output) 

A CSSM_SERVICE_TYPE value identifying the class of security service. 
AttachFlags (output) 


This parameter provides the caller with session specific information associated with the 
module handle. 


KeyHierarchy (output) 
The key hierarchy supplied when the module was attached. 


AttachedMemFuncs (output) 
The memory functions supplied when the module was attached. 
FunctionTable (input/output optional) 


A table of function-name and API function-pointer pairs. The caller provides the name of 
the functions as input. The corresponding API function pointers are returned on output. 
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The function table allows dynamic linking of CDSA interfaces, including interfaces to 
Elective Module Managers, which are transparently loaded by CSSM during the 
CSSM_ModuleAttach () function. The caller of this function should allocate the memory for 
the number of slots required. 


NumFunctionTable (input) 


The number of entries in the F unctionTable parameter. | f no FunctionTableis provided, this 
value must be zero. 


DESCRIPTION 


This function returns the state information associated with the module handle. The information returned by 
this function is that set by the call to the cSSM_ModuleAttach() function. The entry point to this function is 
provided toa service module in a table of upcall functions passed to the service provider during module attach 
processing. 


If the PVC checking for service providers is on, the service provider has to introduce itself before calling this 
function. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 
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CSSM_GetPrivilege 
NAME 
CSSM_GetPrivilege - Get CSSM privilege value (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_GetPrivilege 
(CSSM_PRIVILEGE *Privilege; 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 
Privilege (output) 
The CSSM_PRIVILEGE value currently set. 


DESCRIPTION 


The CSSM_GetPrivilege() function returns the CSSM_PRIVILEGE value currently established in the 
framework. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 
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CSSM_GetSubserviceUI DF romHandle 
NAME 


CSSM_GetSubserviceU| DF romH andle - Complete a subservice unique identifier structure (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_GetSubserviceUIDFromHandle 
(CSSM_MODULE_HANDLE ModuleHandle, 
CSSM_SUBSERVICE_UID_PTR SubserviceUID) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


ModuleHandle (input) 


Handle of the module subservice for which the subservice unique identifier should be 
returned. 


SubserviceUID (output) 


Subservice UID value associated with ModuleHandle. The caller has to allocate the buffer. 


DESCRIPTION 


This function completes a structure containing the persistent unique identifier of the attached module 
subservice, as identified by the input handle. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 
Functions: CSSM_GetM oduleGUI DFromHandle 
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CSSM _Init 


NAME 
CSSM_Init - Initialize CSSM (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_Init ( 
const CSSM_VERSION *Version, 
CSSM_PRIVILEGE_SCOPE Scope, 
const CSSM_GUID * CallerGuid, 
CSSM_KEY_HIERARCHY KeyHierarchy, 
CSSM_PVC_MODE *PvcPolicy, 

const void *Reserved) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


Version (input) 


The major and minor version number of the CSSM release the application is compatible 
with. 


Scope (input) 


The scope of the global privilege value. The scope may either process scope wide 
(CSSM_PRIVILEGE_ SCOPE PROCESS) or thread wide 

(CSSM_PRIVILEGE_ SCOPE_THREAD). This parameter is ignored after the first call to 
CSSM_Init (). 


CallerGuid (input) 


The GUID associated with the caller. This GUID is used to locate the caller's credentials 
when evaluating the request for privileges. 


KeyHierarchy (input) 


The CSSM_KEY_HIERARCHY option directing CSSM what embedded key to use when 
verifying integrity of the named module. 


PvcPolicy (input/output) 


Configures the way in which pointer validation checks will be performed. If not the first call 
to CSSM_Init (), the previously configured policy is returned in the PvcPolicy bitmask and 
the cSSM_Init () call continues processing. If successfully completed, the error code 
CSSMERR_CSSM_PVC_ALREADY_CONFIGURED is returned. 


Value Description 
0 PVC validation is not performed 
1 PVC validation is performed on application modules 
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Value Description 


2 PVC validation is performed on service provider 
modules 
3 Both types of PVC validations are performed 


Reserved (input) 


A reserved input. 


DESCRIPTION 


This function initializes CSSM and verifies that the version of CSSM expected by the application is 
compatible with the version of CSSM on thesystem. This function should be called at least once by the 
application. It is an error to call any function of the CSSM API other than cSsM_Init () beforea call to 
CSSM_Init () has returned successfully (that is, with CSSM_OK). 


Implementations of CSSM might have platform specific characteristics associated with the implementation of 
CSSM_SetPrivilege() API. The privilege value might have thread specific scope or process specific scope. 
The application can specify the anticipated scope at cSSM_Init (). If the anticipated scope is not appropriate 
for the implementation, an error is returned. The scope can be configured only once. Subsequent attempts to 
configure scope are ignored. 


CSSM integrity model includes the ability to make and check assertions about trusted dynamically loaded 
libraries. Checking assertions happens while the program executes. It is Known as Pointer Validation 
Checking (PVC). Pointer validation checking can be applied every time execution flow crosses the CSSM API 
or SPI interfaces. 


Performing pointer validation checks has two purposes: 


e It allows exportation of CSSM. 
e It aids in detering unanticipated run-time modification of the program. 


The CSSM can be configured to bypass pointer validation under some circumstances. Pointer validation 
cannot be bypassed when privileged operations are being performed. 


The prerequisites for performing PVC on another module, be it service provider, CSSM, or other library, are: 
« Themodule must have been signed and have an accompanying signed manifest. 

« Themodule must be loaded into process address space. 

e« An entry-point into the module must be available. 


Typically, the entry points are discovered when a module's functions are called by another module. The CSSM 
performs pointer validation checks based on the configured checking policy. Checking policies are established 
by the manufacturers of CSSM and other libraries. The checking policy to be applied during execution is 
configured using the cSSM_Init () call. The policy can be configured once during the life of the process and 
occurs the first time CSSM_Init () is called. 


PVC POLICY CONFIGURATION OPTIONS 


Pointer validation checking can be applied at the CSSM API interface, the CSSM SPI interface, or both. The 
CSSM vendor can configure a default policy through instructions contained in the CSSM signed manifest. 
Manifest attributes pertaining to pointer validation checking are defined as follows: 
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Module 


Tag Value 


Description 


CSSM 


CSSM 


CSSM 


CSSM 


App 


App 


App 


App 


CDSA_PVC_API unspecified 


CDSA_PVC_API OFF 


CDSA PVC SPI unspecified 


CDSA_PVC_SPI OFF 


CDSA_PVC_API EXEMPT 


CDSA_PVC_API unspecified 


CDSA_PVC_SPI EXEMPT 


CDSA_PVC SPI unspecified 


CSSM will perform PVC 
checks at the API 
boundary. 


CSSM will not perform 
PVC checks at the API 
boundary. 


CSSM will perform PVC 
checks at the SPI 
boundary. 


CSSM will not perform 
PVC checks at the SPI 
boundary. 


The calling module is 
allowed to override the 
CSSM policy for the API 
boundary. 


The calling module 
cannot weaken the 
CSSM API policy. 


The calling module is 
allowed to override the 
CSSM policy for the SPI 
boundary. 


The calling module 
cannot weaken the 
CSSM SPI policy. 


The PvcPolicy parameter to CSSM_Init () configures the run-time policy for the process. The PvcPolicy 
parameter is a bitmask allowing both API and SPI policies to be specified simultaneously. Unspecified policies 
default to the most conservative operational mode. CSSM performs pointer validation checks unless explicitly 
disabled. Application modules cannot override CSSM policy unless exemptions are explicitly granted. The 
following table shows the what policies can be configured for various manifest attribute values: 


CSSM Manifest 


Calling Module Manifest 


Acceptable PvcPolicy Values 


CDSA_PVC_API=<n/a> 
CDSA_PVC_API=OFF 
CDSA_PVC_API=<n/a> 
CDSA_PVC_API=OFF 


CDSA_PVC_API=EXEMPT 
CDSA_PVC_API=EXEMPT 
CDSA_PVC_API=<n/a> 
CDSA_PVC_API|=<n/a> 


API checks: off (0) or on (1) 
API checks: off (0) or on (1) 
API checks: on (1) 

API checks: off (0) or on (1) 


The following table shows the PvcPolicy configuations available for the SPI: 
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SSM Manifest Calling Module Manifest Acceptable PvcPolicy Values 


CDSA_PVC_SPI=<n/a> CDSA_PVC_SPI=EXEMPT SPI checks: off (0) or on (2) 
CDSA_PVC_SPI=OFF CDSA_PVC_SPI=EXEMPT SPI checks: off (0) or on (2) 
CDSA_PVC_SPI=<n/a> CDSA_PVC_SPI=<n/a> SPI checks: on (2) 

CDSA_PVC_SPI=OFF CDSA_PVC_SPIl=<n/a> SPI checks: off (0) or on (2) 


If an application module does not have a manifest and CSSM requires the application module be subject to 
pointer validation checks, then pointer validation checks fail and CSSM will not operate with the anonymous 
module. All service provider modules are expected to have signed manifests. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CSSM_SCOPE_NOT_SUPPORTED 
CSSMERR_CSSM_PVC_ALREADY_CONF IGURED 
CSSMERR_CSSM_INVALID_PVC 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 
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CSSM_Introduce 


NAME 
CSSM_Introduce - Identify an executable module (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_Introduce 
(const CSSM_GUID *ModuleID, 
CSSM_KEY_HIERARCHY KeyHierarchy) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


ModuleID (input) 


The CSSM_GUID of the calling library or other library that might call CDSA interfaces. 
The GUID is used to locate the signed manifest credentials of the named module to 
calculate module integrity information. 


KeyHierarchy (input) 


The CSSM_KEY_HIERARCHY option directing CSSM what embedded key to use when 
verifying integrity of the named module. 


DESCRIPTION 


The CcSSM_Introduce() function identifies a dynamically loadable executable module (for example, DLL) to 
the CSSM framework. CSSM uses the McduleID information to locate the signed manifest and library on the 
host platform. The Module Directory Service (MDS) should be used to obtain theinformation. CSSM performs 
an integrity cross-check on the module identified by ModuleID and caches the result in an internal structure. 
The integrity cross-check uses the KeyHierarchy information to determine which classes of embedded public 
keys must serve as anchors when doing certificate path validation. I f the export key hierarchy is specified, the 
set of export privileges contained in the manifest are retrieved from the manifest and saved with the integrity 
state information in the cache. Privileges granted to a module are accepted only if the manifest sections 
containing the privilege set have been signed by a principal in the export key hierarchy class and that hash of 
the module binary is part of the hash of the privilege attributes. 


The cSSM_Introduce() can be called at any time after cSSM_Init (), by any module, on behalf of any module. 


Once a module is introduced into CSSM the load location of the module must not change. If the load location 
changes then the module must be reintroduced. Once introduced, the module load location, integrity, and 
privilege information is held until cSSM_Terminate () is called or the process terminates. Initialization of 
internal data structures maintaining the table of introductions is performed when cSSM_Init () is called. 


If CSSM_Introduce () is called on behalf of another module, then the caller needs to make sure that the other 
module is loaded into the process address space. If the library is already loaded into process address space, 
but a reference to the library cannot be obtained, a different error is returned 
(CSSMERR_CSSM_LIB_REF_NOT_FOUND). 
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RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CSSM_INVALID_KEY_HIERARCHY 
CSSMERR_CSSM_LIB_REF_NOT_FOUND 


SEE ALSO 
Inta CDSA Application Devdoper's Guide 
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cssm_IsFuncCallValid 


NAME 
cssm_IsFuncCallValid - Check secure linkage (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI cssm_IsFuncCallValid 
(CSSM_MODULE_HANDLE hAddin, 
CSSM_PROC_ADDR SrcAddress, /* application */, 
CSSM_PROC_ADDR DestAddress, 
CSSM_PRIVILEGE InPriv, 
CSSM_PRIVILEGE *OutPriv, 


CSSM_BITMASK Hints, 
CSSM_BOOL * IsOK) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


hAddIn (input) 


The handle identifying the attach-session whose caller and callee scope is being tested by 
this function. 


SrcAddress (input/optional) 


An address to be tested for containment within the application that requested and created 
the attach-session identified by the module handle. 


DestAddress (input/optional) 


An address within a service module. The destination address must be valid for the service 
provider associated with the attach-session identified by the module handle. 


InPriv (input) 


The privilege value to be checked. Privilege checks apply to both SrcAddress and 
DestAddress. 


Out Priv (output) 

If non-NULL, the global privilege will be checked and returned in OutPriv. 
Hints (input) 

A flag providing search hints. 
IsOK (output) 

CSSM_TRUE if success, CSSM_FALSE if fail. 
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DESCRIPTION 


This function checks secure linkage between an application and a service module. Based on address scope of 
the application and the service module associated with the attach handle, CSSM determines whether the 
SrcAddress is within an associated application and DestAddress is within the associated service module. 
The scope of the application and the service module is determined by their respective signed manifest 
credentials, which attest to the integrity of each entity. 


This function uses the input privilege value InPriv to compare against the privilege range associated with 
the ranges for SrcAddress and DestAddres. The privilege check is performed when the InPriv privilege 
valueis non-NULL.IftheEMM wants the global privilege value to be checked, InPrivis zero and OutPrivis 
non-NULL. CSSM will return the privilege valuein outPriv. If integrity only checks are to be performed, 
InPriv is zeroand OutPriv is NULL. 


Another parameter called Hints is used to help CSSM efficiently perform the integrity and privilege 
verification operations. Hints helps CSSM know where to look to find the desired state information. In the 
regular case, CSSM will look for SrcAddress in the CallerList and DestAddress in theAttachList. For 
callback functions, the SrcAddress and DestAddress are likely tobein AttachList. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 
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CSSM_ListAttachedModuleManagers 


NAME 


CSSM_ListAttachedM oduleM anagers - Get a list of GUIDs for the attached module 
manager(CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_ListAttachedModuleManagers 
(uint32 *NumberOfModuleManagers, 
CSSM_GUID_PTR ModuleManagerGuids) 


LIBRARY 


Common Security Services Manager library (cdsa$Sincssm300_shr.exe) 


PARAMETERS 


NumberOfModuleManagers (input/output) 


The number of GUI Ds in the array. I f the array is not large enough, then the actual number 
needed is returned and the error CSSMERR_CSSM_BUFFER_TOO_SMALL is returned. 
The caller should then allocate an appropriately sized list and call the function again. If the 
supplied list is larger than needed, the number of module managers found is returned and 
no error is set. 


ModuleManagerGuids (input/output) 


A pointer to an array of CSSM_GUID structures, one per active module manager. The caller 
allocates this array. 


DESCRIPTION 


This function returns a list of GUIDs for the currently attached and active module managers in the CSSM 
environment. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CSSM_BUFFER_TOO_SMALL 
CSSMERR_CSSM_INVALID_GUID 


SEE ALSO 
Inta CDSA Application Devdoper's Guide 
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CSSM_ModuleAttach 


NAME 
CSSM_ModuleAttach - Attach and verify a service provider module (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_ModuleAttach 
(const CSSM_GUID *ModuleGuid, 

const CSSM_VERSION *Version, 

const CSSM_API_MEMORY_FUNCS *MemoryFuncs, 
uint32 SubservicelID, 

CSSM_SERVICE_TYPE SubServiceType, 
CSSM_ATTACH_FLAGS AttachFlags, 
CSSM_KEY_HIERARCHY KeyHierarchy, 
CSSM_FUNC_NAME_ADDR *FunctionTable, 
uint32 NumFunctionTable, 

const void *Reserved, 
CSSM_MODULE_HANDLE_ PTR NewModuleHandle) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


ModuleGuid (input) 


A pointer tothe CSSM_GUID structure containing the global unique identifier for the CSP 
module. 


Version (input) 

The major and minor version number of CDSA that the application is compatible with. 
MemoryFuncs (input) 

A structure containing pointers to the memory routines. 
SubservicelID (input) 


A SubServicelD identifying a particular subservice within the module. Subservice!|Ds can 
be obtained from MDS or gleaned from insertion events reported through the callback 
function installed through CSSM_ModuleLoad(). Modules that provide only one service can 
use zero as their subservice | D. 


SubServiceType (input) 


A service mask describing the type of service the caller is requesting of the service provider 
module. 


AttachFlags (input) 
A mask representing the caller's request for session-specific services. 


KeyHierarchy (input) 
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The CSSM_KEY_HIERARCHY option directing CSSM what embedded key to use when 
verifying integrity of the named module. 


Funct ionTable (input/output/optional) 


A table of function-name and API function-pointer pairs. The caller provides the name of 
the functions as input. The corresponding API function pointers are returned on output. 
The function table allows dynamic linking of CDSA interfaces, including interfaces to 
Elective Module Managers (EM Ms), which are transparently loaded by CSSM during 
CSSM_ModuleAttach (). 


NumFunctionTable (input) 


The number of entries in the FunctionTable parameter. If no FunctionTable is provided, 
this value must be Zero. 


Reserved (input) 
This field is reserved for future use. It should always be set to zero 
NewModuleHandle (output) 


A new module handle that can be used to interact with the requested service provider. The 
value will be set to CSSM_INVALID_HANDLE if the function fails. 


DESCRIPTION 


This function attaches the service provider module and verifies that the version of the module expected by the 
application is compatible with the version on the system. The module can implement subservices (described 
in your service provider's documentation). The caller can specify a specific subservice provided by the module. 


If the subservice is Supported as part of the CSSM framework as well as by an EMM, ModuleAttach attaches 
the Service Provider tothe CSSM framework. If the subservice is supported only by an EMM, ModuleAttach 
loads the appropriate EMM. The service provider is given an indication of whether it is being attached to the 
CSSM framework or an EMM. 


The caller can provide a function table containing function names for the desired services. On output each 
function name is matched with an API function pointer. The caller can use the pointers to invoke service 
module operations through CSSM. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 

Errors are described in the CDSA Technical Standard. 
CSSMERR_CSSM_INVALID_ADDIN_FUNCTION_TABLE 
CSSMERR_CSSM_EMM AUTHENTICATE FATLED 
CSSMERR_CSSM_ADDIN_ AUTHENTICATE FAILED 
CSSMERR_CSSM_INVALID_SERVICE_MASK 
CSSMERR_CSSM_MODULE_NOT_LOADED 
CSSMERR_CSSM_INVALID_SUBSERVICEID 
CSSMERR_CSSM_INVALID_KEY_ HIERARCHY 
CSSMERR_CSSM_INVALID_GUID 
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SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 
Functions: CSSM_ModuleDetach 
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CSSM_ModuleDetach 


NAME 
CSSM_ModuleDetach - Detach application from service provider module (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_ModuleDetach 
(CSSM_MODULE_HANDLE ModuleHandle) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


ModuleHandle (input) 


The handle that describes the service provider module. 


DESCRIPTION 


This function detaches the application from the service provider module. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 
Functions: CSSM_ModuleAttach 
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CSSM_ModuleLoad 


NAME 
CSSM_ModuleLoad - Initialize the security service module (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_ModuleLoad 

(const CSSM_GUID *ModuleGuid, 
CSSM_KEY_HIERARCHY KeyHierarchy, 
CSSM_API_ModuleEventHandler AppNotifyCallback, 
void* AppNotifyCallbackCtx) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 
ModuleGuid (input) 

The GUID of the module selected for loading. 
KeyHierarchy (input) 


The CSSM_KEY_HIERARCHY option directing CSSM what embedded key to use when 
verifying integrity of the named module. 


AppNotifyCallback (input/optional) 


The event notification function provided by the caller. This defines the callback for event 
notifications from the loaded (and later attached) service module. 


AppNotifyCallbackCtx (input/optional) 


When the selected service module raises an event, this context is passed as an input to the 
event handler specified by AppNot i fyCallback. CSSM does not interpret or modify the 
value of AppNotifyCallbackCtx. 


DESCRIPTION 


This function initializes the security service module. Initialization includes registering the application's 
module-event handler and enabling events with the security service service module. The application can 
choose to provide an event handler function to receive notification of insert, remove, and fault events. The 
specified event handler is the single callback point for all attached sessions with the specified service module. 


The function CcSSM_Init () must be invoked prior to calling CSSM_ModuleLoad(). The function 
CSSM_ModuleAttach() can be invoked multiple times per call to CSSM_ModuleLoad (). 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 
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ERRORS 


Errors are described in the CDSA Technical Standard. 


CSSMERR_CSSM_INVALID_GUID 

CSSMERR_CSSM_ADDIN_LOAD_FAILED 
CSSMERR_CSSM_EMM_LOAD_FAILED 
CSSMERR_CSSM_INVALID_KEY_HIERARCHY 


SEE ALSO 
Inta CDSA Application Devdoper's Guide 
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CSSM_ModuleUnload 


NAME 
CSSM_ModuleUnload - Deregister event notification callbacks (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_ModuleUnload 

(const CSSM_GUID *ModuleGuid, 
CSSM_API_ModuleEventHandler AppNotifyCallback, 
void* AppNotifyCallbackCtx) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 
ModuleGuid (input) 

The GUID of the module selected for unloading. 
AppNotifyCallback (input/optional) 


The event notification function to be deregistered. The function must have been provided by 
the caller in CSSM_ModuleLoad(). 


AppNot ifyCal lbackCtx (input/optional) 


The event notification context that was provided in the corresponding call to 
CSSM_ModuleLoad(). 


DESCRIPTION 


The function deregisters event notification callbacks for the caller identified by ModuleGuid. The 
CSSM_ModuleUnload() function is the analog call to CSSM_ModuleLoad (). If all callbacks registered with 
CSSM areremoved, then CSSM unloads the service module that was loaded by calls to CSSM_ModuleLoad(). 
Calls to CSSM_ModuleUnload() that arenot matched with a previous call to CSSM_ModuleLoad() result in an 
error. 


The CSSM uses the three input parameters ModuleGuid, AppNotifyCallback, and AppNotifyCallbackCtx 
to uniquely identify registered callbacks. 


This function should be invoked after all necessary calls to CSSM_ModuleDetach() have been performed. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 
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CSSMERR_CSSM_ADDIN_UNLOAD_FATIL 


CSSMERR_CSSM_EMM_UNLOAD_FAILED 
CSSMERR_CSSM_EV 


ED 


WE 


ENT_NOTIFICATION_CALLBACK_NOT_FOUND 


SEE ALSO 


Inta CDSA Application Devdoper's Guide 
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cssm_ReleaseAttachF unctions 


NAME 
cssm_ReleaseAttachF unctions - Release lock on the SP function table (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI cssm_ReleaseAttachFunctions 
(CSSM_MODULE_HANDLE hAddIn) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


hAddIn (input) 


The handle identifying the attach-session whose function table is to be released by this 
function. 


DESCRIPTION 


This function releases the lock on the SP function table for the service module identified by the module 
handle. The SPI function table was obtained by the elective module manager through the 
cssm_GetAttachFunctions () operation. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 
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CSSM_SetContext 


NAME 
CSSM_SetContext - Replace all context information (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_SetContext 
(CSSM_CC_HANDLE CCHandle, 
const CSSM_CONTEXT *Context) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 
CCHandle (input) 

The handle to the context. 
Context (input) 


The context data describing the service to replace the current service associated with 
context handle CCHandle. 


DESCRIPTION 


This function replaces all context information associated with an existing context specified by ccHandle. The 
contents of the basic context structure and all attributes included in that structure are replaced by the 
context structure and attribute values contained in the Context input parameter. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CSSM_INVALID_ATTRIBUTE 
CSSMERR_CSSM_INVALID_CONTEXT_HANDLE 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 
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Online Help 
Functions: CSSM_GetContext 
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CSSM SetPrivilege 


NAME 
CSSM_SetPrivilege - Store privilege value in CSSM framework (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_SetPrivilege 
(CSSM_PRIVILEGE Privilege) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 
Privilege (input) 


The CSSM_PRIVILEGE value to be applied to subsequent calls to CSSM interfaces. 


DESCRIPTION 


The cSSM_SetPrivilege () function accepts as input a privilege value and stores it in the CSSM framework. 
The integrity credentials of the module calling cSSM_SetPrivilege () must be verified by CSSM before the 
privilege value is updated. Integrity credentials are established using CSSM_Introduce(). CSSM will 
perform a pointer validation check to ensure the caller has been previously introduced. The 
CSSM_SetPrivilege() function will fail if no integrity information can be found for the caller. 


After pointer validation checks, CSSM verifies the requested privilege is authorized. This is done by 
comparing Privilege with the set of privileges contained in the caller manifest. If Privilege is not a 
member, the CSSM_SetPrivilege () call fails. 


Subsequent calls to the framework that require privileges inherit the privilege value previously established 
by CSSM_SetPrivilege (). CSSM will perform pointer validation checks on theAPI caller before servicing the 
API call. If OK, then the Privilege value is supplied to the SPI function. 


Internally, CSSM builds and maintains privilege information based on the chosen scope of the 
implementation. The scope may be dictated by the capabilities of the platform hosting the CSSM. If threading 
is available, the privilege value can be associated with the thread | D of the currently executing thread. In this 
scenario, CSSM can manage a table of tuples consisting of threadID and privilege value. If threading is not 
available, the privilege value can be global to the process. 


Because the selected privilege value is shared, the application programmer should take precautions to reset 
the privilege value whenever program flow leaves the caller's module and again when control flow returns. In 
general, any time there is a possibility for cSSM_SetPrivilege() to be called while within the context of the 
security critical section, CSSM_SetPrivilege() should be called again. Otherwise, the module receiving 
execution control could have called cSSM_SetPrivilege (), resulting in the privilege value being reset. 


Data structures used to maintain the global privilege value should be initialized in cSSM_Init (). This 
includes lock initialization and preliminary resource allocation. The cSSM_Init () function is assumed to be 
idempotent with respect to shared structure initialization. This means cSSM_Init () will ensurea single 
thread initializes the shared structure and subsequent calls to CSSM_Init () will not reinitialize it. A 
reference count of calls to CSSM_Init () is needed to ensure matching calls to cSSM_Terminate() are handled. 
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Resource cleanup is performed at CSSM_Terminate () after the reference count falls to zero. The last call to 
CSSM_Terminate() results in shared resources being freed and lock structures being released. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 
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CSSM_SPI_ModuleAttach 
NAME 

CSSM_SPI_ModuleAttach - Attach a service provider module(CDSA) 
SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMSPI CSSM_SPI_ModuleAttach 
(const CSSM_GUID *ModuleGuid, 

const CSSM_VERSION *Version, 

uint32 SubservicelID, 
CSSM_SERVICE_TYPE SubServiceType, 
CSSM_ATTACH_FLAGS AttachFlags, 
CSSM_MODULE_HANDLE ModuleHandle, 
CSSM_KEY_HIERARCHY KeyHierarchy, 
const CSSM_GUID *CssmGuid, 

const CSSM_GUID *ModuleManagerGuid, 
const CSSM_GUID *CallerGuid, 

const CSSM_UPCALLS *Upcalls, 
CSSM_MODULE_FUNCS_PTR *FuncTbl) 


LIBRARY 


Common Security Services Manager library (cdsa$Sincssm300_shr.exe) 


PARAMETERS 
ModuleGuid (input) 

The CSSM_GUID of the invoked service provider module. 
Version (input) 


The major and minor version number of the required level of system services and features. 
The service module must determine whether its services are compatible with the required 
version. 


Subserviceld (input) 


The identifier for the requested subservice within this module. If only one service is 
provided by the module, then subservicelId can be zero. 


SubServiceType (output) 


A CSSM_SERVICE_MASK indicating the type of services provided by the service module 
and the ordering of the function table returned in the output parameter FuncTbl. 


AttachFlags (input) 
A mask representing the caller's request for session-specific services. 
ModuleHandle (input) 


TheCSSM_HANDLE valueassigned by CSSM and associated with the attach session being 
created by this function. 


KeyHierarchy (input) 
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The CSSM_KEY_HIERARCHY option directing CSSM which embedded key or keys to use 
when verifying integrity of the named modules. 


CssmGuid (input) 

The CSSM_GUID of the CSSM invoking this function. 
ModuleManagerGuid (input) 

The CSSM_GUID of the module that will route calls to the service provider. 
CallerGuid (input) 


The CSSM_GUID of the caller who invoked cSSM_ModuleAttach (), which resulted in 
CSSM invoking this function. 


Upcalls (input) 


A set of function pointers the service module must use to obtain selected CSSM services and 
to manage application memory. The memory management functions are provided when the 
application invokes CSSM_ModuleAttach().CSSM forwards these function pointers with 
CSSM service function pointers to the module. 


FuncTbl (output) 


A CSSM_MODULE_FUNCS table containing pointers to the service module functions the 
caller can use. CSSM uses this table to proxy calls from an application caller to the add-in 
service module. 


DESCRIPTION 


This function is invoked by CSSM once for each invocation of CSSM_ModuleAttach (), specifying the module 
identified by ModuleGuid. Four entities are stakeholders in this function and each is identified by a 
CSSM_GUID value: 


Service Module 


The executing service provider performing the cSSM_SPI_ModuleAttach() operation. The 
module is identified by ModuleGuid. 


CSSM 
The CSSM that invoked the service module. CSSM is identified by CssmGuid. 
ModuleManagerGuid 
The module that will be routing calls to the service provider. This value will be the same as 
CssmGuid if CSSM is managing the calls to this service provider. 
Caller 


The entity that invoked CSSM through the cSSM_ModuleAttach () function. The caller is 
identified by callerGuid. 


The service provider module should perform an integrity check of CSSM. CssmGuid can be used to locate 
CSSM's signed manifest credentials. The service provider can require an integrity check of the Caller. The 
CallerGuid parameter can be used to locate the Caller's signed manifest credentials. The KeyHierarchy flag 
identifies the class of embedded public keys CSSM will use to check the integrity of the service provider. If the 
manifest for the target module does not encounter an embedded key for all the key classes in KeyHierarchy, 
the integrity cross-check fails. 
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The service module must verify compatibility with the system version level specified by Version. If the 
version is not compatible, then this function fails. The service module should perform all initializations 
required to support the new attached session and should return a function table for the SPI entry points that 
can be invoked by CSSM in response to API invocations by callerGuid. CSSM uses this function table to 
dispatch requests for the attach session created by this function. Each attach session has its own function 
table. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 
Functions: CSSM_SPI_ModuleDeach, CSSM_SPI_Module_oad 
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CSSM_SPI_ModuleDetach 


NAME 
CSSM_SPI_ModuleDetach - Notify service module of a context event (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMSPI CSSM_SPI_ModuleDetach 
(CSSM_MODULE_HANDLE ModuleHandle) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


ModuleHandle (input) 


The CSSM_HANDLE value associated with the attach session being terminated by this 
function. 


DESCRIPTION 


This function is invoked by CSSM once for each invocation of CSSM_ModuleDetach () specifying the 
attach-session identified by ModuleHandle. The function entry point for CSSM_SPI_ModuleDetach is included 
in the module function table cSSM_MODULE_FUNCS returned to CSSM as output of a successful 
CSSM_SPI_ModuleAttach. 


The service module must perform all cleanup operations associated with the specified attach handle. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 
Functions: CSSM_SPI_ModuleAttach, CSSM_SPI_ModuleUnload 
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CSSM_SPI_ModuleLoad 


NAME 
CSSM_SPI_ModuleLoad - Initialize process between CSSM and the add-in service module (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMSPI CSSM_SPI_ModuleLoad 

(const CSSM_GUID *CssmGuid, 

const CSSM_GUID *ModuleGuid, 
CSSM_SPI_ModuleEventHandler CssmNotifyCallback, 
void* CssmNotifyCallbackCtx) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 
CssmGuid (input) 

The CSSM_GUID of the caller. Used to locate the caller's signed manifest credentials. 
ModuleGuid (input) 


The CSSM_GUID of the invoked service provider module. Used to locate the module's 
signed manifest credentials. 


CssmNotifyCallback (input) 


A function pointer for the CSSM event handler that manages events of type 
CSSM_ MODULE EVENT. 


CssmNotifyCallbackCtx (input) 


The context to be returned to CSSM as input on each callback to the event handler defined 
by CssmNot ifyCallback. 


DESCRIPTION 


This function completes the module initialization process between CSSM and the add-in service module. 
Before invoking this function, CSSM verifies the add-in service module's manifest credentials. If the 
credentials verify this module is loaded (physically if required), the cSSM_SPT_ModuleLoad() function is 
invoked. 


The CssmGuid parameter identifies the caller and should be used by the module to locate the caller's signed 
manifest credentials and to complete integrity verification and secure linkage checks on the caller. The 
ModuleGuid identifies the invoked module and should be used by the module to locate its credentials and to 
complete an integrity self-check. 


The CssmNot ifyCallback and CssmNotifyCallbackCtx parameters define a callback and callback context 
respectively. The module must retain this information for later use. The module should use the callback to 
notify CSSM of module events of type CSSM_ MODULE _ EVENT in any ongoing, attached sessions. 
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RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 
Functions: CSSM_SPI_ModuleAttach, CSSM_SPI_ModuleUnload 


234 


CSSM_SPI_ModuleUnload 


NAME 
CSSM_SPI_ModuleUnload - Disable events and deregister CSSM event notification (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMSPI CSSM_SPI_ModuleUnload 
(const CSSM_GUID *CssmGuid, 

const CSSM_GUID *ModuleGuid, 
CSSM_SPI_ModuleEventHandler CssmNotifyCallback, 
void* CssmNotifyCallbackCtx) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 
CssmGuid (input) 
The CSSM_GUID of the caller. 
ModuleGuid (input) 
The CSSM_GUID of the invoked service provider module. 
CssmNotifyCallback (input) 


A function pointer for the CSSM event handler that manages events of type 
CSSM_ MODULE EVENT. 


CssmNotifyCallbackCtx (input) 


The context to be returned to CSSM as input on each callback to the event handler defined 
by CssmNotifyCallback. 


DESCRIPTION 


This function disables events and deregisters the CSSM event-notification function. The add-in service 
module can perform cleanup operations, reversing the initialization performed in CSSM_SPI_ModuleLoad(). 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 
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SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 
Functions: CSSM_SPI_ModuleDetach, CSSM_SPI_Module_oad 
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CSSM_Terminate 
NAME 
CSSM_Terminate - Terminate the use of CSSM (CDSA) 


SYNOPSIS 


#include <cssm.h> 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


None 


DESCRIPTION 


This function terminates the caller's use of CSSM. CSSM can clean up all internal states associated with the 
calling application. This function must be called once by each application. 


CSSM_Terminate() must be called one time for each time CSSM_Init () was previously called. 


CSSM services remain available to the program until the final call to CSSM_Terminate () completes. After 
that final call, all information introduced by the caller (including privileges, handles, contexts, introduced 
libraries, and so forth) is lost, and it is an error to subsequently call any CSSM API function other than 
CSSM_Init (). 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 
Functions CSSM_Init 
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CSSM_TP_RetrieveCredResult 


NAME 


CSSM_TP_RetrieveCredResult - Return the results of the credentials request (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSS 


(CSSM_TP_HANDLE 


MAPI CSSM_TP_RetrieveCredResult 
TPHandle, 


const CSSM_DATA *ReferencelIdentifier, 
const CSSM_TP_CALLERAUTH_CONTEXT *CallerAuthCredentials, 


sint32 *] 


= 


Estimat 


CSSM_BOOL *Conf 


CSSM_TP 


RESULT. 


edTime, 
irmationRequired, 


LIBRARY 


Common Security Services M anager library (cdsa$incssm300_shr.exe) 


SET_PTR *RetrieveOutput ) 


PARAMETERS 


TPHandle (input) 


The handle that describes the certification authority module used to perform this function. 


Referenceldentifier (input) 


A reference identifier that uniquely identifies the cSSM_TP_SubmitCredRequest () call that 
initiated the certificate service request whose results are returned by this function. The 
identifier persists across application executions and becomes undefined when all local 
processing of the request has completed. 


Local processing is completed in one of two ways: 


¢ For certificate services that do not require explicit confirmation by the requester, the 
reference identifier is invalidated when the corresponding 
CSSM_TP_RetrieveCredResult () function completes (by returning valid results or by 
failure, which blocks returned results). 


e For certificate services that require explicit confirmation by the requester, the reference 
identifier is invalidated by successfully invoking the function 
CSSM_TP_ConfirmCredResult (). 


CallerAuthCredentials (input/optional) 
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This structure contains a set of caller authentication credentials. The authentication 
information can be a passphrase, a PIN, a completed registration form, a certificate, or a 
template of user-specific data. The required set of credentials is defined by the service 
provider module and recorded in arecord in the MDS Primary relation. Multiple credentials 
can be required. If the local service provider module does not require credentials from a 
caller, then the credentials field of this verification context structure can be NULL. The 
structure optionally contains additional credentials that can be used to support the 
authentication process. Authentication credentials required by the authority should be 
included in the Request Input. The local TP module can forward information from 
CallerAuthCredentials tothe authority, as appropriate, but is not required to do so. 


Est imatedTime (output) 


The number of seconds estimated before the results of a requested service will be returned 
to the requester. When the local TP module or the authority process cannot estimate the 
time required to perform the requested service, the output value for estimated time is 
CSSM_ESTIMATED_TIME UNKNOWN. 


Confirmat ionRequired (output) 


A Boolean value indicating whether the caller must invoke CSSM_TP_ConfirmCredResult () 
to acknowledge retrieving the results of the service request. CSSM_TRUE indicates the 
caller must call cSSM_TP_ConfirmCredResult (). CSSM_FALSE indicates that the caller 
must not call cSSM_TP_ConfirmCredResult (). The value of this output parameter is not 
applicable until CSSM_TP_RetrieveCredResult () completes by returning results of the 
request or terminates in unrecoverable failure. 


RetrieveOutput (output) 


A pointer to the results returned by the authority in response to the service requests 
submitted by cSSM_TP_SubmitCredRequest (). The output results are ordered 
corresponding to the requests. The structure of the response set is determined by the type of 
request. The caller and the service provider must retain knowledge of the request type 
associated with the ReferenceIdentifier. 


DESCRIPTION 


This function returns the results of a CSSM_TP_SubmitCredRequest () call. 


The single identifier ReferenceIdentifier denotes the cSSM_TP_SubmitCredRequest () invocation that 
initiated the request. 


It is possible that the results are not ready to be retrieved when this call is made. In that case, an 
Est imatedTime to complete processing is returned. The caller must attempt to retrieve the results again after 
the estimated time to completion has elapsed. 


This function can fail in total for any one of the following reasons: 


¢ Thereference identifier is invalid. 
¢ TheTP process cannot be located. 
¢ TheTP process encountered a fatal error when attempting to process the requests. 


When this function completes, the set of return results is ordered corresponding tothe order of the originating 
request. 


Some certificate services require the requester to confirm retrieval of the results. The 
ConfirmationRequired parameter indicates whether the caller must confirm completion of 
CSSM_TP_RetrieveCredResult () by calling CSSM_TP_ConfirmCredResult (). 
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RETURN VALUE 


A CSSM_RETURN value combined with estimated time to indicate one of three results: 


Complete Function Function Return 


RetrieveOutput 


EstimatedTime 


Result Value 


Request results returnedto CSSM_OK 
caller 


Request results not ready, CSSM_OK 
but expected in the future 


Fatal Error, results will (ICSSM_OK) 
never be returned 


Non-NULL pointer 


NULL pointer 


NA 


NA 


CSSM_ESTIMATED_TIM 
E_ UNKNOWN or 
<estimated seconds> 


NA 


The (!CSSM_OK) return value represents a specific error code. 


ERRORS 


Errors are described in the CDSA Technical Standard. 


ER 


CSSMERR_TP_INVALID_IDENTIFIER_POINT 
CSSMERR_TP_INVALID_IDENTIFIER 
CSSMERR_TP_INVALID_CALLERAUTH_CONTE 
CSSMERR_TP_INVALID_POLICY_IDENTIFIE 
CSSMERR_TP_INVALID_TIMESTRING 
CSSMERR_TP_INVALID_STOP_ON_POLICY 
CSSMERR_TP_INVALID_CALLBACK 
CSSMERR_TP_INVALID_ANCHOR_CER 
CSSMERR_TP_CERTGROUP_INCOMPLETE 
CSSMERR_TP_INVALID_DL_HANDLE 
CSSMERR_TP_INVALID_DB_HANDLE 
CSSMERR_TP_INVALID_DB_LIST_POINTER 
CSSMERR_TP_INVALID_DB_LIST 
CSSMERR_TP_AUTHENTICATION_FAILED 
CSSMERR_TP_INSUFFICIENT_CREDENTIALS 
CSSMERR_TP_NOT_TRUSTED 
CSSMERR_TP_CERT_REVOKED 
CSSMERR_TP_CERT_SUSPENDED 
CSSMERR_TP_CERT_EXPIRED 
CSSMERR_TP_CER OT_VALID_YET 
CSSMERR_TP_INVALID_CERT_AUTHORITY 
CSSMERR_TP_INVALID_SIGNATURE 
CSSMERR_TP_INVALID_NAME 
CSSMERR_TP_REQUEST_LOS 
CSSMERR_TP_REQUEST_REJECTED 
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XT_POINT!I 
RS 


ER 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 
CSSM_TP_SubmitCredR equest 
Functions for the TP SPI: 
TP_SubmitCredR equest 
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CSSM_Unintroduce 


NAME 
CSSM_Unintroduce - Remove module (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSM_Unintroduce 
(const CSSM_GUID *ModulelID) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


ModuleID (input) 


The CSSM_GUID of the calling library or other library that can call CDSA interfaces. The 
GUID is used to locate the module integrity and privilege information. If the ModuleID is 
NULL, then the caller will be unintroduced. 


DESCRIPTION 


The CSSM_Unintroduce () function removes the module referenced by ModuleID from the list of module 
information maintained by the CSSM framework. 


A caller can unintroduce modules other than itself if the caller has been previously introduced. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CSSM_INVALID_GUID 


SEE ALSO 
Inta CDSA Application Devdoper's Guide 
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CSSM_UpdateContextAttributes 


NAME 
CSSM_UpdateContextAttributes - Update context attribute values (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_UpdateContextAttributes 
(CSSM_CC_HANDLE CCHandle, 
uint32 NumberOfAttributes, 
const CSSM_CONTEXT_ATTRIBUTE *ContextAttributes) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CCHandle (input) 

The handle to the existing context. 
NumberOfAttributes (input) 

The number of CSSM_CONTEXT_ATTRIBUTE structures to allocate. 
ContextAttributes (input) 


Pointer to data that describes the attributes to be associated with this context. 


DESCRIPTION 


This function updates one or more context attribute values stored as part of an existing context specified by 
CCHandle. The basic context structure is not modified by this function. Only the context attributes are 
updated. 


The NumberOfAttributes parameter specifies the number of attributes to update. The new attribute values 
are specified in CcontextAttributes. If an attribute provided in ContextAttributes is already present in 
the existing context, the existing value is replaced by the new value. If an attribute provided in 
ContextAttributes is not present in the existing context, then the new attribute is added. Attribute values 
are never deleted from the existing context. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CSSM_INVALID_CONTEXT_HANDLE 
CSSMERR_CSSM_INVALID_ATTRIBUTE 
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SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 
Functions: CSSM_DeleteContextAttributes, CSSM_Ge&tContextAttri bute 
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DecryptData 


NAME 
DecryptData: CSSM_DecryptData, CSP_DecryptData - Decrypt buffer data (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_DecryptData 
(CSSM_CC_HANDLE CCHandle, 

const CSSM_DATA *CipherBufs, 

uint32 CipherBufCount, 

CSSM_DATA_ PTR ClearBufs, 

uint32 ClearBufCount, 

uint32 *bytesDecrypted, 
CSSM_DATA_PTR RemData) 

SPL 
CSSM_RETURN CSSMCSPI CSP_DecryptData 
(CSSM_CSP_HANDLE CSPHandle, 
CSSM_CC_HANDLE CCHandle, 

const CSSM_CONTEXT *Context, 

const CSSM_DATA *CipherBufs, 

uint32 CipherBufCount, 

CSSM_DATA_PTR ClearBufs, 

uint32 ClearBufCount, 

uint32 *bytesDecrypted, 
CSSM_DATA_PTR RemData, 
CSSM_PRIVILEGE Privilege) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


API PARAMETERS 


CCHandle (input) 


The handle that describes the context of this cryptographic operation used to link to the 
CSP-managed information. 


CipherBufs (input) 

A pointer to a vector of CSSM_DATA structures that contain the data to be decrypted. 
CipherBufCount (input) 

The number of CipherBufs. 
ClearBufs (output) 


A pointer toa vector of CSSM_DATA structures that contain the decrypted data resulting 
from the decryption operation. 


ClearBufCount (input) 


The number of ClearBufs. 
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bytesDecrypted (output) 
A pointer to uint 32 for the size of the decrypted data in bytes. 
RemData (output) 


A pointer tothe CSSM_DATA structure for the remaining plain text if there is not enough 
buffer space available in the output data structures. 


SPI PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform calls to CSSM for the memory functions managed by CSSM. 


Context (input) 
A pointer to CSSM_CONTEXT structure that describes the attributes with this context. 
Privilege (input) 


The export privilege to be applied during the cryptographic operation. This parameter is 
forwarded to the CSP after CSSM verifies the caller and service provider privilege set 
includes the specified PRIVILEGE. 


DESCRIPTION 


This function decrypts all data contained in the set of input buffers using information in the context. The 
CSSM_QuerySize() (CSSM API), or CcSP_QuerySize () (CSP SPI), function can be used to estimate the output 
buffer size required. The minimum number of buffers required to contain the resulting plain text is produced 
as output. If the plain text result does not fit within the set of output buffers, the remaining plain text is 
returned in the single output buffer RemData. 


The CSP can require that the cryptographic context include access credentials for authentication and 
authorization checks when using a private key or a secret key. 


NOTES FOR API 


The output is returned to the caller either by filling the caller-specified buffer or by using the application's 
declared memory allocation functions to allocate buffer space. To specify a specific, pre-allocated output 
buffer, the caller must provide an array of one or more CSSM_DATA structures, each containing a Length 
field value greater than zero and anon-NULL data pointer field value. To specify automatic output buffer 
allocation by the CSP, the caller must provide an array of one or more CSSM_DATA structures, each 
containing a Length field value equal to zero and a NULL data pointer field value. The application is always 
responsible for deallocating the memory when it is no longer needed. | n-place decryption can be done by 
supplying the same input and output buffers. 


NOTES FOR SPI 


The output is returned to the caller as specified in Buffer Management for Cryptographic Services. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 
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ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CSP_BLOCK_SIZE_MISMATCH 
CSSMERR_CSP_OUTPUT_LENGTH_ERROR 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 


Functions for the CSSM API: 


CSSM_QuerySize, CSSM_EncryptData, CSSM_DecryptDatal nit, CSSM_DecryptDataU pdate 
CSSM_DecryptDataFinal, CSSM_DecryptP, CSSM_DecryptDatal nitP 


Functions for the CSP SPI: 


CSP_QuerySize CSP_EncryptData, CSP_DecryptDatal nit, CSP_DecryptDataU pdate, 
CSP_DecryptDataF inal 
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DecryptDataF inal 


NAME 
DecryptDataF inal: CSSM_DecryptDataFinal, CSP_DecryptDataFinal - Finalize staged decryption 
process (CDSA) 

SYNOPSIS 

#include <cssm.h> 

API: 

CSSM_RETURN CSSMAPI CSSM_DecryptDataFinal 


(CSSM_CC_HANDLE CCHandle, 
CSSM_DATA_PTR RemData) 
SPI: 
CSSM_RETURN CSSMCSPI CSP_DecryptDataFinal 
(CSSM_CSP_HANDLE CSPHandle, 
CSSM_CC_HANDLE CCHandle, 

CSSM_DATA_PTR RemData) 


LIBRARY 


Common Security Services M anager library (cdsa$incssm300_shr.exe) 


API PARAMETERS 


CCHandle (input) 


The handle that describes the context of this cryptographic operation used to link to the 
CSP-managed information. 


RemData (output) 
A pointer tothe CSSM_DATA structure for the last decrypted block, if necessary. 


SPI PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform calls to CSSM for the memory functions managed by CSSM. 


DESCRIPTION 


This function finalizes the staged decryption process by returning any remaining plain text not returned in 
the previous staged decryption call. The plain text is returned in a single buffer. 


NOTES FOR API 


The output is returned to the caller either by filling the caller-specified buffer or by using the application's 
declared memory allocation functions to allocate buffer space. To specify a specific, pre-allocated output 

buffer, the caller must provide an array of one or more CSSM_DATA structures, each containing a Length 
field value greater than zero and anon-NULL data pointer field value. To specify automatic output buffer 
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allocation by the CSP, the caller must provide an array of one or more CSSM_DATA structures, each 
containing a Length field value equal to zero and a NULL data pointer field value. The application is always 
responsible for deallocating the memory when it is no longer needed. 


NOTES FOR SPI 


The output is returned to the caller as specified in Buffer Management for Cryptographic Services. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CSP_BLOCK_SIZE_MISMATCH 
CSSMERR_CSP_OUTPUT_LENGTH_ERROR 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 

CSSM_DecryptData, CSSM_DecryptDatal nit, CSSM_DecryptDataU pdate 
Functions for the CSP SPI: 

CSP_DecryptData, CSP_DecryptDatal nit, CSP_DecryptDataU pdate 


249 


DecryptDatal nit 


NAME 


DecryptDatal nit: CSSM_DecryptDatal nit, CSP_DecryptDatal nit - Initialize the staged decrypt 
function(CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM _DecryptDataInit 
(CSSM_CC_HANDLE CCHandle) 

SPI: 
CSSM_RETURN CSSMCSPI CSSM_CSP_DecryptDataInit 
(CSSM_CSP_HANDLE CSPHandle, 

CSSM_CC_HANDLE CCHandle, 

const CSSM_CONTEXT *Context, 

CSSM_PRIVILEGE Privilege) 


LIBRARY 


Common Security Services M anager library (cdsa$incssm300_shr.exe) 


API PARAMETERS 


CCHandle (input) 


The handle that describes the context of this cryptographic operation used to link to the 
CSP-managed information. 


SPI PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform calls to CSSM for the memory functions managed by CSSM. 


Context (input) 
Pointer to CSSM_ CONTEXT structure that describes the attributes with this context. 
Privilege (input) 


The export privilege to be applied during the cryptographic operation. This parameter is 
forwarded to the CSP after CSSM verifies the caller and service provider privilege set 
includes the specified PRIVILEGE. 


DESCRIPTION 
This function initializes the staged decrypt function. 


The CSP can require that the cryptographic context include access credentials for authentication and 
authorization checks when using a private key or a secret key. 
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RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 


indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


None specific to this call. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 


Functions for the CSSM API: 


CSSM_DecryptData, CSSM_DecryptDataU pdate CSSM_DecryptDataFinal, CSSM_DecryptDataP, 
CSSM_DecryptDatal nitP 


Functions for the CSP SPI: 
CSP_DecryptData, CSP_DecryptDataU pdate CSP_DecryptDataF inal 
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DecryptDatal nitP 


NAME 
DecryptDatal nitP - Intialize the staged decrypt function with privilege (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_DecryptDataInitP 
(CSSM_CC_HANDLE CCHandle, 
CSSM_PRIVILEGE Privilege) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 
Privilege (input) 
The privilege to be applied during the cryptographic operation. 


See CSSM_DecryptDataInit () for other parameters. 


DESCRIPTION 


This function is similar to CSSM_DecryptDataInit (). It also accepts a USEE tag as a privilege request 
parameter. CSSM checks that either its own privilege set or the application's privilege set (if the application 
is signed) includes the tag. If the tag is found and the service provider privilege set indicates that it is 
supported, the tag is forwarded to the service provider. 


For staged operations using privilege initialization functions CSSM_DecryptDataInitP (), the completion 
functions CSSM_DecryptDataUpdate() and CSSM_DecryptDataFinalize() are used. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


None specific to this call. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 
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Online Help 


Functions: CSSM_DecryptData, CSSM_EncryptDatal nit, CSSM_EncryptDataU pdate, 
CSSM_EncryptDataFinal, CSSM_EncryptDataP, CSSM_EncryptDatalnitP, CSSM_DecryptP, 
CSSM_DecryptDatal nitP, CSSM_QuerySize 
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DecryptDataP 


NAME 
DecryptDataP - Decrypt data with privilege (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_DecryptDataP 
(CSSM_CC_HANDLE CCHandle, 

const CSSM_DATA *CipherBufs, 

uint32 CipherBufCount, 

CSSM_DATA_PTR ClearBufs, 

uint32 ClearBufCount, 

uint32 *bytesDecrypted, 

CSSM_DATA_PTR RemData, 

CSSM_PRIVILEGE Privilege) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 
Privilege (input) 
The privilege to be applied during the cryptographic operation. 


See CSSM_DecryptData () for other parameters. 


DESCRIPTION 


This function is similar to CSSM_DecryptData (). It also accepts a USEE tag as a privilege request parameter. 
CSSM checks that either its privilege set or the application's privilege set (if the application is signed) 
includes the tag. I f the tag is found and the service provider privilege set indicates that it is supported, the tag 
is forwarded to the service provider. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CSP_BLOCK_SIZE_MISMATCH 
CSSMERR_CSP_OUTPUT_LENGTH_ERROR 
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SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 


Functions: CSSM_DecryptData, CSSM_EncryptDatal nit, CSSM_EncryptDataU pdate, 
CSSM _EncryptDataFinal, CSSM_EncryptDataP, CSSM_EncryptDatalnitP, CSSM_DecryptP, 
CSSM_DecryptDatal nitP, CSSM_QuerySize 
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DecryptDataU pdate 


NAME 


DecryptDataU pdate: CSSM_DecryptDataU pdate, CSP_DecryptDataU pdate - Continue the staged 
decryption process (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_DecryptDataUpdate 
(CSSM_CC_HANDLE CCHandle, 

const CSSM_DATA *CipherBufs, 

uint32 CipherBufCount, 

CSSM_DATA_PTR ClearBufs, 

uint32 ClearBufCount, 

uint32 *bytesDecrypted) 

SPL 
CSSM_RETURN CSSMCSPI CSP_DecryptDataUpdate 
(CSSM_CSP_HANDLE CSPHandle, 

CSSM_CC_HANDLE CCHandle, 

const CSSM_DATA *CipherBufs, 

uint32 CipherBufCount, 

CSSM_DATA_PTR ClearBufs, 

uint32 ClearBufCount, 

uint32 *bytesDecrypted) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


API PARAMETERS 


CCHandle (input) 


The handle that describes the context of this cryptographic operation used to link to the 
CSP-managed information. 


CipherBufs (input) 

A pointer toa vector of CSSM_DATA structures that contain the data to be operated on. 
CipherBufCount (input) 

The number of CipherBufs. 
ClearBufs (output) 


A pointer toa vector of CSSM_DATA structures that contain the decrypted data resulting 
from the decryption operation. 


ClearBufCount (input) 
The number of ClearBufs. 
bytesDecrypted (output) 
A pointer to uint32 for the size of the decrypted data in bytes. 
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SPI PARAMETER 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform calls to CSSM for the memory functions managed by CSSM. 


DESCRIPTION 


This function continues the staged decryption process over all data in the set of input buffers. There can be 
algorithm-specific and token-specific rules restricting the lengths of data in CSSM_DecryptUpdate () calls, but 
multiple input buffers are supported. The minimum number of buffers required to contain the resulting plain 
text is produced as output. Excess output buffer spaceis not remembered across staged decryption calls. Each 
staged call begins filling one or more new output buffers. The CSSM_QuerySize() (CSSM API), or 
CSP_QuerySize() (CSP SPI), function can be used to estimate the output buffer size required for each update 
call. 


NOTES FOR API 


The output is returned to the caller either by filling the caller-specified buffer or by using the application's 
declared memory allocation functions to allocate buffer space. To specify a specific, preallocated output buffer, 
the caller must provide an array of one or more CSSM_DATA structures, each containing a Length field value 
greater than zero and a non-NULL data pointer field value. To specify automatic output buffer allocation by 
the CSP, the caller must provide an array of one or more CSSM_DATA structures, each containing a Length 
field value equal to zero and a NULL data pointer field value. The application is always responsible for 
deallocating the memory when it is no longer needed. |n-place decryption can be done by supplying the same 
input and output buffers. 


NOTES FOR SPI 


The output is returned to the caller as specified in Buffer Management for Cryptographic Services. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 


Errors are described in the CDSA Technical Standard. 
None specific to this call. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 


Functions for the CSSM API: 
CSSM_QuerySize, CSSM_DecryptData, CSSM_DecryptDatal nit, CSSM_DecryptDataF inal 
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Functions for the CSP SPI: 
CSP_QuerySize CSP_DecryptData, CSP_DecryptDatal nit, CSP_DecryptDataF inal 
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DeriveKey 


NAME 
DeriveK ey: CSSM_DeriveK ey, CSP_DeriveK ey - Derive new symmetric key (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 
CSSM_RETURN CSSMAPI CSSM_DeriveKey 

(CSSM_CC_HANDLE CCHandle, 

CSSM_DATA_PTR Param, 

uint32 KeyUsage, 

uint32 KeyAttr, 

const CSSM_DATA *KeyLabel, 

const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry, 
CSSM_KEY_PTR DerivedKey) 

SPS 
CSSM_RETURN CSSMCSPI CSP_DeriveKey 

(CSSM_CSP_HANDLE CSPHandle, 

CSSM_CC_HANDLE CCHandle, 

const CSSM_CONTEXT *Context, 

CSSM_DATA_PTR Param, 

uint32 KeyUsage, 

uint32 KeyAttr, 

const CSSM_DATA *KeyLabel, 

const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry, 
CSSM_KEY_PTR DerivedKey) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


API PARAMETERS 


CCHandle (input) 
The handle that describes the context of this cryptographic operation. 


Param (input/output) 


This parameter varies depending on the derivation algorithm. Password based derivation 


algorithms use this parameter to return a cipher block chaining initialization vector. 
Concatenation algorithms use this parameter to get the second item to concatenate. 


KeyUsage (input) 

A bit mask indicating all permitted uses for the new derived key. 
KeyAttr (input) 

A bit mask defining other attribute values for the new derived key. 
KeyLabel (input/optional) 

Pointer to a byte string that will be used as the label for the derived key. 


CredAndAclEntry (input/optional) 
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A structure containing one or more credentials authorized for creating a key and the 
prototype ACL entry that will control future use of the newly created key. The credentials 
and ACL entry prototype can be presented as immediate values or callback functions can be 
provided for use by the CSP to acquire the credentials and/or the subject of the ACL entry 
interactively. If the CSP provides public access for creating a key, then the credentials can 
be NULL. If the CSP defines a default initial ACL entry for the new key, then the ACL entry 
prototype can be empty. 


DerivedKey (output) 
A pointer toa CSSM_KEY structure that returns the derived key. 


SPI PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform up calls to CSSM for the memory functions managed by CSSM. 


Context (input) 
Pointer to CSSM_ CONTEXT structure that describes the attributes with this context. 


DESCRIPTION 


This function derives a new symmetric key using the context and/or information from the base key in the 
context. The CSP can require that the cryptographic context include access credentials for authentication and 
authorization checks when using a private key or a secret key. 


Authorization policy can restrict the set of callers who can create a new resource. In this case, the caller must 
present a set of access credentials for authorization. Upon successfully authenticating the credentials, the 
template that verified the presented samples identifies the ACL entry that will be used in the authorization 
computation. If the caller is authorized, the new resource is created. 


The caller must provide an initial ACL entry to be associated with the newly created resource. This entry is 
used to control future access to the new resource and (since the subject is deemed to be the "Owner") exercise 
control over its associated ACL. The caller can specify the following items for initializing an ACL entry: 


Subject 


A CSSM LIST structure, containing the type of the subject and a template value that can 
be used to verify samples that are presented in credentials when resource access is 
requested. 


Delegation flag 


A value indicating whether the Subject can delegate the permissions recorded in the 
AuthorizationTag. (This item only applies to public key subjects). 


Authorization tag 

The set of permissions that are granted to the Subject. 
Validity period 

The start time and the stop time for which the ACL entry is valid. 
ACL entry tag 

A user-defined string value associated with the ACL entry. 
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The service provider can modify the caller-provided initial ACL entry to conform to any 
innate resource-access policy that the service provider may be required to enforce. If the 
initial ACL entry provided by the caller contains values or permissions that are not 
supported by the service provider, then the service provider can modify the initial ACL 
appropriately or can fail the request to create the new resource. Service providers list their 
supported AuthorizationTag values in their Module Directory Services primary record. 


The CSP can require that the cryptographic context include access credentials for 
authentication and authorization checks when using a private key or a secret key. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CSP_KEY_LABEL_ALREADY_EXISTS 


COMMENTS 


The KeyData field of the CSSM_KEY structureis allocated by the CSP. The application is required to free this 
memory using the CSSM_FreeKey () (CSSM API), or CSP_FreeKey () (CSP SPI) call, or with the memory 
functions registered for the cSPHandle. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 
Functions: CSSM_CSP_CreateDeriveKeyContext 
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DigestData 


NAME 
DigestData: CSSM_DigestData, CSP_DigestData - Compute message digest (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 
CSSM_RETURN CSSMAPI CSSM_DigestData 
(CSSM_CC_HANDLE CCHandle, 

const CSSM_DATA *DataBufs, 

uint32 DataBufCount, 

CSSM_DATA_PTR Digest) 

SPI: 
CSSM_RETURN CSSMCSPI CSP_DigestData 
(CSSM_CSP_HANDLE CSPHandle, 
CSSM_CC_HANDLE CCHandle, 

const CSSM_CONTEXT *Context, 

const CSSM_DATA *DataBufs, 

uint32 DataBufCount, 

CSSM_DATA_PTR Digest) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


API PARAMETERS 


CCHandle (input) 


The handle that describes the context of this cryptographic operation used to link to the 
CSP-managed information. 


Dat aBufs (input) 

A pointer toa vector of CSSM_DATA structures that contain the data to be operated on. 
Dat aBufCount (input) 

The number of DataBufs. 


Digest (output) 
A pointer tothe CSSM_DATA structure for the message digest. 


SPI PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform up calls to CSSM for the memory functions managed by CSSM. 


Context (input) 
Pointer to CSSM_CONTEXT structure that describes the attributes with this context. 
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DESCRIPTION 


This function computes a message digest for all data contained in the set of input buffers. 


NOTES FOR API 


The output is returned to the caller either by filling the caller-specified buffer or by using the application's 
declared memory allocation functions to allocate buffer space. To specify a specific, preallocated output buffer, 
the caller must provide an array of one or more CSSM_DATA structures, each containing a Length field value 
greater than zero and a non-NULL data pointer field value. To specify automatic output buffer allocation by 
the CSP, the caller must provide an array of one or more CSSM_DATA structures, each containing a Length 
field value equal to zero and a NULL data pointer field value. The application is always responsible for 
deallocating the memory when it is no longer needed. 


NOTES FOR SPI 


The output is returned to the caller as specifed in Buffer Management for Cryptographic Services. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CSP_OUTPUT_LENGTH_ERROR 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 

CSSM_DigestDatal nit, CSSM_DigestDataU pdate, CSSM_DigestDataFinal, CSSM_DigestDataClone 
Functions for the CSP SPI: 

CSP_DigestDatal nit, CSP_DigestDataU pdate CSP_DigestDataFinal, CSP_DigestDataClone 
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DigestDataClone 


NAME 


DigestDataClone: CSSM_DigestDataClone, CSP_DigestDataClone - Clone a staged message digest 
(CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_DigestDataClone 
(CSSM_CC_HANDLE CCHandle, 

CSSM_CC_HANDLE *ClonednewCCHandle) 

SPI: 
CSSM_RETURN CSSMCSPI CSP_DigestDataClone 
(CSSM_CSP_HANDLE CSPHandle, 
CSSM_CC_HANDLE CCHandle, 

CSSM_CC_HANDLE ClonednewCCHandle) 


LIBRARY 


Common Security Services M anager library (cdsa$incssm300_shr.exe) 


API PARAMETERS 
CCHandle (input) 

The handle that describes the context of a staged message digest operation. 
ClonednewCCHandle (output) 


The cloned digest context handle. The handle will be set to CSSM_INVALID_HANDLE if 
the function fails. 


SPI PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform calls to CSSM for the memory functions managed by CSSM. 


DESCRIPTION 


This function clones a given staged message digest context with its cryptographic attributes and intermediate 
result. 


NOTES 


When a digest context is cloned, a new context is created with data associated with the parent context. 
Changes made to the parent context after calling this function will not be reflected in the cloned context. The 
cdoned context could be used with the cSSM_DigestDataUpdate() and CSSM_DigestDataFinal () functions. 
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RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 


indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


None specific to this call. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 

CSSM_DigestData, CSSM_DigestDatal nit, CSSM_DigestDataUpdate, CSSM_DigestDataFinal 
Functions for the CSP SPI: 

CSP_DigestData, CSP_DigestDatal nit, CSP_DigestDataU pdate CSP_DigestDataFinal 


265 


DigestDataF inal 


NAME 


DigestDataF inal: CSSM_DigestDataF inal, CSP_DigestDataF inal - Finalize the staged message 
digest (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_DigestDataFinal 
(CSSM_CC_HANDLE CCHandle, 

CSSM_DATA_PTR Digest) 

SP Es 
CSSM_RETURN CSSMCSPI CSP_DigestDataFinal 
(CSSM_CSP_HANDLE CSPHandle, 
CSSM_CC_HANDLE CCHandle, 

CSSM_DATA_PTR Digest) 


LIBRARY 


Common Security Services M anager library (cdsa$incssm300_shr.exe) 


API PARAMETERS 


CCHandle (input) 


The handle that describes the context of this cryptographic operation used to link to the 
CSP-managed information. 


Digest (output) 
A pointer tothe CSSM_DATA structure for the message digest. 


SPI PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform up calls to CSSM for the memory functions managed by CSSM. 


DESCRIPTION 


This function finalizes the staged message digest function. 


NOTES FOR API 


The output is returned to the caller either by filling the caller-specified buffer or by using the application's 


declared memory allocation functions to allocate buffer space. To specify a specific, preallocated output buffer, 
the caller must provide an array of one or more CSSM_DATA structures, each containing a Length field value 


greater than zero and a non-NULL data pointer field value. To specify automatic output buffer allocation by 
the CSP, the caller must provide an array of one or more CSSM_DATA structures, each containing a Length 
field value equal to zero and a NULL data pointer field value. The application is always responsible for 
deallocating the memory when it is no longer needed. 
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NOTES FOR SPI 


The output is returned to the caller as specified in Buffer Management for Cryptographic Services. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. . 


CSSMERR_CSP_OUTPUT_LENGTH_ERROR 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 

CSSM_DigestData, CSSM_DigestDatal nit, CSSM_DigestDataUpdate CSSM_DigestDataCl one 
Functions for the CSP SPI: 

CSP_DigestData, CSP_DigestDatal nit, CSP_DigestDataU pdate CSP_DigestDataClone 
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DigestDatal nit 


NAME 


DigestDatal nit: CSSM_DigestDatal nit, CSP_DigestDatal nit - Initialize the staged message digest 
(CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_DigestDataInit 
(CSSM_CC_HANDLE CCHandle) 

SPI: 
CSSM_RETURN CSSMCSPI CSP_DigestDataInit 
(CSSM_CSP_HANDLE CSPHandle, 
CSSM_CC_HANDLE CCHandle, 

const CSSM_CONTEXT *Context) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


API PARAMETERS 


CCHandle (input) 


The handle that describes the context of this cryptographic operation used to link to the 
CSP-managed information. 


SPI PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform up calls to CSSM for the memory functions managed by CSSM. 


Context (input) 
Pointer to CSSM_ CONTEXT structure that describes the attributes with this context. 


DESCRIPTION 


This function initializes the staged message digest function. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


None specific to this call. 
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SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 

CSSM_DigestData, CSSM_DigestDataUpdate, CSSM_DigestDataClone, CSSM_DigestDataF inal 
Functions for the CSP SPI: 

CSP_DigestData, CSP_DigestDataU pdate, CSP_DigestDataClone, CSP_DigestDataF inal 
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DigestDataU pdate 


NAME 
DigestDataU pdate: CSSM_DigestDataU pdate - Continue the staged process of digesting (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 
CSSM_RETURN CSSMAPI CSSM_DigestDataUpdate 
(CSSM_CC_HANDLE CCHandle, 

const CSSM_DATA *DataBufs, 

uint32 DataBufCount) 

SPL: 
CSSM_RETURN CSSMCSPI CSP_DigestDataUpdate 
(CSSM_CSP_HANDLE CSPHandle, 

CSSM_CC_HANDLE CCHandle, 

const CSSM_DATA *DataBufs, 

uint32 DataBufCount) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


API PARAMETERS 


CCHandle (input) 


The handle that describes the context of this cryptographic operation used to link to the 
CSP-managed information. 


DataBufs (input) 

A pointer toa vector of CSSM_DATA structures that contain the data to be operated on. 
Dat aBufCount (input) 

The number of DataBufs. 


SPI PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform up calls to CSSM for the memory functions managed by CSSM. 


DESCRIPTION 


This function continues the staged process of digesting all data contained in the set of input buffers. The 
resulting digest value will be returned as part of the staged digesting process. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 
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ERRORS 
Errors are described in the CDSA Technical Standard. 


None specific to this call. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 

CSSM_DigestData, CSSM_DigestDatal nit, CSSM_DigestDataClone, CSSM_DigestDataF inal 
Functions for the CSP SPI: 

Functions: CSP_DigestData, CSP_DigestDatal nit, CSP_DigestDataClone CSP_DigestDataF inal 
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DL_Authenticate 


NAME 
DL_Authenticate: CSSM_DL_Authenticate - Provide authentication credentials (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 
CSSM_RETURN CSSMAPI CSSM_DL_Authenticate 
(CSSM_DL_DB_ HANDLE DLDBHandle, 


CSSM_DB_ACCESS_TYPE AccessRequest, 

const CSSM_ACCESS_CREDENTIALS *AccessCred) 
SPE 
CSSM_RETURN CSSMDLI DL_Authenticate 
(CSSM_DL_DB_ HANDLE DLDBHandle, 
CSSM_DB_ACCESS_TYPE AccessRequest, 


const CSSM_ACCESS_CREDENTIALS *AccessCred) 


LIBRARY 


Common Security Services Manager library (cdsa$Sincssm300_shr.exe) 


PARAMETERS 


DLDBHandle (input) 


The handle pair that describes the add-in data storage library module used to perform this 
function and the data store to which access is being requested. If the form of authentication 
being requested is authentication tothe DL module in general, then the data store handle 

must be NULL. 


AccessRequest (input) 
An indicator of the requested access mode for the data store or DL module in general. 
AccessCred (input) 


A pointer to the set of one or more credentials being presented for authentication by the 
caller. The credentials can apply to the DL module in general or to a particular data store 
managed by this service module. The credentials required for creating new data stores is 
defined by the DL and recorded in a record in the MDS Primary DL relation. The required 
set of credentials to access a particular data storeis defined by the DbInfo record containing 
meta-data for the specified data store. 


The credentials structure can contain multiple types of credentials, as required for 
multi-factor authentication. The credential data can be an immediate value, such as a 
passphrase, PIN, certificate, or template of user-specific data, or the caller can specify a 
callback function the DL can use to obtain one or more credentials. 


DESCRIPTION 


This function allows the caller to provide authentication credentials tothe DL module at a time other than 
data store creation, deletion, open, import, and export. AccessRequest defines the type of access to be 
associated with the caller. If the authentication credential applies to access and use of a DL modulein 
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general, then the data store handle specified in the DLDBHandle must be NULL. When the authorization 
credential is to apply to a specific data store, the handle for that data store must be specified in the 
DLDBHandle pair. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_DL_INVALID_ACCESS_REQUEST 
CSSMERR_DL_INVALID_DB_HANDLE 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 
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DL_ChangeDbAcl 
NAME 


DL_Cha 


SYNOPSIS 


#include <cssm.h> 


API: 


CSSM_R 


(CSSM_ 
const 
const 
SEES 


CSSM_R 


(CSSM_ 
const 


const 


ETURN CSS 
DL_DB_HAN 
CSSM_ACCE 


ngeDbAcl: CSSM_DL_ChangeDbAcl - Edit stored ACL (CDSA) 


IAPI CSSM_DL_ChangeDbAcl 
DLE DLDBHandle, 
SS_CREDENTIALS *AccessCred, 


CSSM_ACL_EDIT *AclEdit) 


ETURN CSS 
DL_DB_HAN 
CSSM_ACCE 


MDLI DL_ChangeDbAcl 
DLE DLDBHandle, 
SS_CREDENTIALS *AccessCred, 


CSSM_ACL_EDIT *AclEdit) 


LIBRARY 


Common Security Services Manager library (cdsa$Sincssm300_shr.exe) 


PARAMETERS 


DLDBHandle (input) 


The handle pair that describes the data storage library module to be used to perform this 
function, and the open data store whose associated ACL entries are to be updated. 


AccessCred (input) 


AclEdit (input) 
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A pointer to the set of one or more credentials used to authenticate and validate the caller's 
authorization to modify the ACL associated with the target data base. Required credentials 
can include zero or more certificates, zero or more caller names, and one or more samples. I f 
certificates and/or caller names are provided as input these must be provided as immediate 
values in this structure. The samples can be provided as immediate values or can be 
obtained through a callback function included in the AccessCred structure. 


A structure containing information that defines the edit operation. Valid operations include 
adding, replacing and deleting entries in the set of ACL entries managed by the service 
provider. The AclEdit can contain information for anew ACL entry and a unique handle 
identifying an existing ACL entry. The information controls the edit operation as follows: 


Value of AclE dit.E ditMode Use of AclEdit.NewEntry and 
AclE dit.OIdE ntryHandle 


CSSM_ACL_EDIT_MODE_ADD Adds anew ACL entry tothe set of ACL entries 
associated with the specified data base. The new ACL 
entry is created from the prototype ACL entry contained 
in NewEntry. OldEntryHand1le is ignored for this 

EditMode. 


Value of AclE dit.E ditMode Use of AclEdit.NewEntry and 
AclE dit.OIdE ntryHandle 


CSSM_ACL_EDIT_MODE_DELETE Deletes the ACL entry identified by OldEntryHandle 
and associated with the specified data base. NewEntry is 
ignored for this EditMode. 


CSSM_ACL_EDIT_MODE_REPLACE Replaces the ACL entry identified by oldEntryHandle 
and associated with the specified data base. The existing 
ACL is replaced based on the ACL entry prototype 
contained in NewEntry. 


When replacing an existing ACL entry, the caller must replace all of the items in an ACL 
entry. The replacement prototype includes: 


Subject type and value 


A CSSM_LIST structure containing a typed Subject. The Subject 
identifies the entity authorized by this ACL entry. 


Delegation flag 


A CSSM_BOOL value indicating whether the subject can delegate the 
permissions recorded in the authorization array. 


Authorization array 


A CSSM_AUTHORIZATIONGROUP structure defining the set of 
operations for which permission is granted to the Subject. 


Validity period 


A CSSM_ACL_VALIDITY_PERIOD structure containing two elements, 
the start time and the stop time for which the ACL entry is valid. 


ACL entry tag 


A CSSM_STRING containing a user-defined value associated with the 
ACL entry. 


DESCRIPTION 


This function edits the stored ACL associated with the target data base identified by DLDBHandle.DBHandle. 
TheACL is modified according to the edit mode and information provided in AclEdit. 


The caller must be authorized to modify the target ACL. Caller authentication and authorization to edit the 
ACL is determined based on the caller-provided AccessCred. 


The caller must be authorized to add, delete or replace the ACL entries associated with the target data base. 
When adding or replacing an ACL entry, the service provider must reject the creation of duplicate ACL 
entries. 


When adding a new ACL entry toan ACL, the caller must provide a complete ACL entry prototype. All ACL 
entry items, except the ACL entry TypedSubject must be provided as an immediate value in 
AclEdit->NewEntry. TheACL entry Subject can be provided as an immediate value, from a verifier with a 
protected data path, from an external authentication or authorization service, or through a callback function 
specified in AclEdit->NewEnt ry->Callback. 
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RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_DL_INVALID_DB_HANDLE 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 
CSSM_DL_Ga&DbAd 
Functions for the DL SPI: 
DL_GetDbAcl 


276 


DL_ChangeDbOwner 
NAME 
DL_ChangeDbOwner: CSSM_DL_ChangeDbOwner - Define a new data base owner (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_DL_ChangeDbOwner 

(CSSM_DL_DB_HANDLE DLDBHandle, 

const CSSM_ACCESS_ CREDENTIALS *AccessCred, 

const CSSM_ACL_OWNER_PROTOTYPE *NewOwner) 

SPL: 

CSSM_RETURN CSSMDLI DL_ChangeDbOwner 

(CSSM_DL_DB_HANDLE DLDBHandle, 

const CSSM_ACCESS_ CREDENTIALS *AccessCred, 
R 


const CSSM_ACL_OWNER_PROTOTYPE *NewOwner) 


LIBRARY 


Common Security Services Manager library (cdsa$Sincssm300_shr.exe) 


PARAMETERS 


DLDBHandle (input) 


The handle pair that describes the data storage library module to be used to perform this 
function, and the open data store whose associated Owner is to be updated. 


AccessCred (input) 


A pointer to the set of one or more credentials used to prove the caller is the current Owner 
of the Data Base. Required credentials can include zero or more certificates, zero or more 
caller names, and one or more samples. If certificates and/or caller names are provided as 
input these must be provided as immediate values in this structure. The samples can be 
provided as immediate values or can be obtained through a callback function included in the 
AccessCred structure. 


NewOwner (input) 


A CSSM_ACL_OWNER_PROTOTYPE defining the new Owner of the Data Base. 


DESCRIPTION 


This function takes a CSSM_ACL_OWNER_PROTOTYPE defining the new Owner of the Data Base. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 
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ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_DL_INVALID_DB_HANDLE 
CSSMERR_DL_INVALID_NEW_OWNER 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 
CSSM_DL_Ga&DbOwner 
Functions for the DL SPI: 
DL_Ga&DbOwner 
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DL_CreateRelation 


NAME 
DL_CreateRelation: CSSM_DL_CreateRelation - Create a new persistent relation (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_DL_CreateRelation 
(CSSM_DL_DB_ HANDLE DLDBHandle, 

CSSM_DB_RECORDTYPE RelationID, 

const char *RelationName, 

uint32 NumberOfAttributes, 

const CSSM_DB_SCHEMA_ATTRIBUTE_INFO *pAttributeInfo, 
uint32 NumberOfIndexes, 
const CSSM_DB_SCHEMA_INDEX_INFO *pIndexInfo) 
SPI: 
CSSM_RETURN CSSMDLI DL_CreateRelation 

(CSSM_DL_DB_ HANDLE DLDBHandle, 

CSSM_DB_RECORDTYPE RelationID, 

const char *RelationName, 

uint32 NumberOfAttributes, 

const CSSM_DB_SCHEMA_ATTRIBUTE_INFO *pAttributeInfo, 
uint32 NumberOfIndexes, 
const CSSM_DB_SCHEMA_INDEX_INFO *pIndexInfo) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


DLDBHandle (input) 


The handle pair that describes the add-in data storage library module to be used to perform 
this function and the open data store in which to insert the new relation record. The 
database should be opened in administrative mode using the 

CSSM_DB_ACCESS PRIVILEGED flag. 


RelationID (input) 


Indicates the type of relation record being added to the data store. 


RelationName (input) 


Indicates the name of the relation being added to the data store. 


NumberOfAttributes (input) 
Indicates the number of attributes specified in pAttributeInfo. 
pAttributelInfo (input) 


A list of structures containing the meta information (schema) describing the attributes for 
the relation being added to the specified data store The list contains at most one entry per 
attribute in the specified record type. 
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NumberOfIndexes (input) 
Indicates the number of indexes specified in pIndexInfo. 
pIndexInfo (input) 


A list of structures containing the meta information (schema) describing the indexes for the 
relation being added to the specified data store. The list contains at most one entry per 
index in the specified record type. 


DESCRIPTION 


This function creates a new persistent relation of the specified type by inserting it into the specified data 
store. The pAttributeInfo and pIndexInfo specify the values contained in the new relation record. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_DL_FIELD_SPECIFIED_MULTIPLE 
CSSMERR_DL_INVALID_ATTRIBUTE_INFO 

CSSMERR_DL_INVALID_DB_HANDLE 
CSSMERR_DL_INVALID_INDEX_INFO 
CSSMERR_DL_INVALID_RECORDTYPE 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 
CSSM_DL_DestroyRdation 
Functions for the DL SPI: 
DL_DestroyRdation 
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DL_DataAbortQuery 


NAME 
DL_DataAbortQuery: CSSM_DL_DataAbortQuery - Terminate DL_DataGetFirst query (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_DL_DataAbortQuery 
(CSSM_DL_DB_ HANDLE DLDBHandle, 

CSSM_HANDLE ResultsHandle) 

SPI: 
CSSM_RETURN CSSMDLI DL_DataAbortQuery 
(CSSM_DL_DB_ HANDLE DLDBHandle, 
CSSM_HANDLE ResultsHandle) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


DLDBHandle (input) 


The handle pair that describes the add-in data storage library module to be used to perform 
this function and the open data store from which records were selected by the initiating 


query. 
Result sHandle (input) 


The selection handle returned from the initial query function. 


DESCRIPTION 


This function terminates the query initiated by DL_DataGetFirst () and allows a DL to release all 
intermediate state information associated with the query, and release any locks on the resource. The 
user/application must call CSSM_DL_DataAbortQuery () at the termination. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_DL_INVALID_DB_HANDLE 
CSSMERR_DL_INVALID_RESULTS_HANDLE 
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SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 
CSSM_DL_DataGedFirst, CSSM_DL_DataGe@Nett 
Functions for the DL SPI: 

DL_DataGeFirst, dL__DataGetNext 
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DL_DataDelete 


NAME 
DL_DataDelete: CSSM_DL_DataDelete - Remove data record (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_DL_DataDelete 

(CSSM_DL_DB_ HANDLE DLDBHandle, 

const CSSM_DB_UNIQUE_RECORD *UniqueRecordIdentifier) 
SPI: 
CSSM_RETURN CSSMDLI DL_DataDelete 

(CSSM_DL_DB_ HANDLE DLDBHandle, 

const CSSM_DB_UNIQUE_RECORD *UniqueRecordIdentifier) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


DLDBHandle (input) 


The handle pair that describes the add-in data storage library module to be used to perform 
this function and the open data store from which to delete the specified data record. 


UniqueRecordIdentifier (input) 


A pointer toa CSSM_DB_UNIQUE_ RECORD identifier containing unique identification of 
the data record to be deleted from the data store. Once the associated record has been 
deleted, this unique record identifier cannot be used in future references, except as an 
argument to DL_FreeUniqueRecord() which must still be called. 


DESCRIPTION 


This function removes the data record specified by the unique record identifier from the specified data store. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_DL_INVALID_DB_HANDLE 
CSSMERR_DL_INVALID_RECORD_UID 
CSSMERR_DL_RECORD_NOT_FOUND 
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SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 
CSSM_DL_Datalnsert 
Functions for the DL SPI: 
DL_Datal nsert 
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DL_DataGetFirst 


NAME 

DL_DataGetFirst: CSSM_DL_DataGetFirst - Get first data record (CDSA) 
SYNOPSIS 
#include <cssm.h> 
API: 
CSSM_RETURN CSSMAPI CSSM_DL_DataGetFirst 
(CSSM_DL_DB_HANDLE DLDBHandle, 
const CSSM_QUERY *Query, 
CSSM_HANDLE_PTR ResultsHandle, 
CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR Attributes, 
CSSM_DATA_PTR Data, 
CSSM_DB_UNIQUE_RECORD_PTR *Uniqueld) 
SPI: 
CSSM_RETURN CSSMDLI DL_DataGetFirst 
(CSSM_DL_DB_HANDLE DLDBHandle, 
const CSSM_QUERY *Query, 
CSSM_HANDLE_PTR ResultsHandle, 
CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR Attributes, 
CSSM_DATA_PTR Data, 
CSSM_DB_UNIQUE_RECORD_PTR *UniquelId) 
LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


DLDBHandle (input) 


The handle pair that describes the add-in data storage library module to be used to perform 
this function and the open data store to search for records satisfying the query. 


Query (input/optional) 


The query structure specifying the selection predicate(s) used to query the data store. The 
structure contains meta information about the search fields and the relational and 
conjunctive operators forming the selection predicate. The comparison values to be used in 
the search are specified in the Attributes field of this Query structure. If a search attribute 
is of tyoe CSSM_DB_ATTRIBUTE_FORMAT_STRING and the search value specified for 
that string includes a null-terminator, then the length count for that string should include 
the terminating character. (If null-terminators are used they should be used consistently, 
storing the terminator as part of the string in the data store, otherwise selection predicates 
will not locate expected matches.) The Query structure attributes also identify the 
particular attributes to be searched by this query. If no query is specified, the DL module 
can return the first record in the data store, performing sequential retrieval, or return an 
error. | f no selection predicates are specified, the DL module can return the first record in 
the data store, performing sequential retrieval, or return an error 
(CSSM_DL_UNSUPPORTED_NUM_SELECTION_PREDS). When selection predicates are 
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specified, the NumberOfValues of the Attribute of each selection predicate must be 1. If 
any selection predicate does not satisfy this requirement, the error 
CSSMERR_DL_INVALID_ QUERY is returned. 


Result sHandle (output) 

This handle should be used to retrieve subsequent records that satisfied this query. 
Attributes (optional-input/output) 

If the Attributes structure pointer is NULL, no values are returned. 


Otherwise, the DataRecordType, NumberOfAttributes and AttributeData fields are read. 
AttributeData must bean array of NumberOfAttributes 
CSSM_DB_RECORD_ATTRIBUTE elements. Only the Info field of each element is used 
on input. The AttributeFormat field of the Info field is ignored on input. 


On output, aCSSM_DB RECORD ATTRIBUTE structure containing a list of all or the 
requested attribute values (subset) from the retrieved record. The SemanticInformation 
field is set. For each CSSM_DB_ATTRIBUTE_DATA contained in the attributeData 
array, the NumberOfValues field is set to reflect the size of the Value array which is 
allocated by the DL using the application specified allocators. Each CSSM_DATA in the 
Value array will have it's Data field as a pointer to data allocated using the application 
specified allocators containing the attributes value, and have it's Length set to the length of 
the value. 


All values for an attribute are returned (this could be 0). All fields in the Info field of the 
CSSM_DB_ATTRIBUTE_DATA are left unchanged except for the Att ributeFormat field, 
which is set to reflect the schema. 


Data (optional-input/output) 


Data values contained in the referenced memory are ignored during processing and are 
overwritten with the retrieved opaque object. On output, aCSSM_DATA structure 
containing the opaque object stored in the retrieved record. 


Uniqueld (output) 


If successful and (at least) a record satisfying the query has been found, then this parameter 
returns a pointer toa CSSM_UNIQUE_RECORD_PTR structure containing a unique 
identifier associated with the retrieved record. This unique identifier structure can be used 
in future references to this record using this DLDBHand1le pairing. It may not be valid for 
other DLHandles targeted to this DL module or to other DBHandles targeted to this data 
store. If there are no records satisfying the query, then this pointer is NULL and 
CSSM_DL_DataGetFirst () must return CSSM_DL_ENDOFDATA,; in this case a normal 
termination condition has occurred. The CSSM_DL_FreeUniqueRecord () must be used to 
deallocate this structure. 


DESCRIPTION 


This function retrieves the first data record in the data store that matches the selection criteria. The selection 
criteria (including selection predicate and comparison values) is specified in the Query structure. If the Query 
specifies an attribute that is not defined in the database's meta-information, an error condition is returned. 
The DL module can use internall y-managed indexing structures to enhance the performance of the retrieval 
operation. This function selects the first record satisfying the query based on the list of Attributes and the 
opaque Data object. The output buffers for the retrieved record are allocated by this function using the 
memory management functions provided during the module attach operation. This function also returns a 
results handle to be used when retrieving subsequent records satisfying the query. 
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Additional matching records are iteratively retrieved using the CSSM_DL_DataGetNext () function . The data 
storage module supports one of two retrieval models: 


¢ Transactional - all query results are determined at initial query evaluation. Results do not change during 
an incremental retrieval process. 


e FileSystem Scan - query results are selected during the incremental retrieval process. Records matching 
the query may be added to or deleted from the underlying data store during the iterative retrieval. The 
caller may receive the new matching records and not received the deleted records. 


The caller can determine which retrieval model is supported by examining the encapsulated product 
description for this data storage module. 


If the query selection criteria also specifies time for space limits for executing the query, those limits also 
apply ro retrieval of the additional selected data records retrieved using the CSSM_DL_DataGetNext () 
function. Finally, this function returns a unique record identifier associated with the retrieved record. This 
structure can be used in future references to the retrieved data record. Once a user has finished using a 
certain query, it must call CSSM_DataAbort Query () for releasing resources that CSSM uses. If all records 
satisfying the query have been retrieved, then query is automatically terminated. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 

Errors are described in the CDSA Technical Standard. 
CSSMERR_DL_ENDOFDATA 
CSSMERR_DL_FIELD_SPECIFIED_MULTIPLE 
CSSMERR_DL_INCOMPATIBLE FIELD FORMAT 
CSSMERR_DL_INVALID_DB HANDLE 

CSSMERR_DL_ INVALID FIELD NAMF 
CSSMERR_DL_INVALID_ PARSING MODULE 
CSSMERR_DL_INVALID_ QUERY 
CSSMERR_DL_INVALTID_RECORDTYPE 
CSSMERR_DL_INVALTID_RECORD_UID 
CSSMERR_DL_UNSUPPORTED_FIELD_ FORMAT 
CSSMERR_DL_UNSUPPORTED_NUM_SELECTION_PREDS 
CSSMERR_DL_UNSUPPORTED_OPERATOR 
CSSMERR_DL_UNSUPPORTED_QUERY 
CSSMERR_DL_UNSUPPORTED_QUERY_LIMITS 

SEE ALSO 

Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 
CSSM_DL_DataGa&Next, CSSM_DL_DataAbortQuery 
Functions for the DL SPI: 
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DL_DataGetNext, DL_DataAbortQuery 
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DL_DataGetFromUniqueRecordld 


NAME 


DL_DataGetF romU niqueRecordl d: CSSM_DL_DataGetF romU niqueRecordl d - Get data record 
(CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 
CSSM_RETURN CSSMAPI CSSM_DL_DataGetFromUniqueRecordId 
(CSSM_DL_DB_HANDLE DLDBHandle, 

const CSSM_DB_UNIQUE_RECORD_PTR UniqueRecord, 
CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR Attributes, 
CSSM_DATA_PTR Data) 
SPI: 
CSSM_RETURN CSSMDLI DL_DataGetFromUniqueRecordIid 
(CSSM_DL_DB_HANDLE DLDBHandle, 

const CSSM_DB_UNIQUE_RECORD_PTR UniqueRecord, 
CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR Attributes, 


CSSM_DATA_PTR Data) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


DLDBHandle (input) 


The handle pair that describes the add-in data storage library module to be used to perform 
this function and the open data store to search for the data record. 


UniqueRecord (input) 


The pointer to a unique record structure returned from a DL_DataInsert, 
DL_DataGetFirst, Of DL_DataGetNext operation. 


Attributes (optional-input/output) 
If the Attributes structure pointer is NULL, no values are returned. 


Otherwise, the DataRecordType, NumberOfAttributes and AttributeData fields are read. 
AttributeData must bean array of NumberOfAttributes 
CSSM_DB_RECORD_ATTRIBUTE elements. Only the Info field of each element is used 
on input. The AttributeFormat field of the Info field is ignored on input. 


On output, aCSSM_DB RECORD ATTRIBUTE structure containing a list of all or the 
requested attribute values (subset) from the retrieved record. The SemanticInformation 
field is set. For each CSSM_DB_ATTRIBUTE_DATA contained in the attributeData 
array, the NumberOfValues field is set to reflect the size of the Value array which is 
allocated by the DL using the application specified allocators. Each CSSM_DATA in the 
Value array will have it's Data field as a pointer to data allocated using the application 
specified allocators containing the attributes value, and have it's Length set tothe length of 
the value. 
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All values for an attribute are returned (this could be 0). All fields in the Info field of the 
CSSM_DB_ATTRIBUTE_DATA are left unchanged except for the Att ributeFormat field, 
which is set to reflect the schema. 


Data (optional-input/output) 


Data values contained in the referenced memory are ignored during processing and are 
overwritten with the retrieved opaque object. On output, aCSSM_DATA structure 
containing the opaque object stored in the retrieved record. If the pointer is data structure 
pointer is NULL, the opaque object is not returned. 


DESCRIPTION 


This function retrieves the data record and attributes associated with this unique record identifier. The 
Attributes parameter can specify a subset of the attributes to be returned. If Attributes specifies an 
attribute that is not defined in the database's meta-information, an error condition is returned. The output 
buffers for the retrieved record are allocated by this function using the memory management functions 
provided during the module attach operation. The DL module can use an indexing structure identified in the 
UniqueRecordId to enhance the performance of the retrieval operation. 


The DL should assume that the value of CSSM_QUERY_FLAGS is when performing this operation. In 
particular this means that if the data of a key record is being retrieved, the DL will return a CSSM_KEY 
structure with a key reference 


If the record referenced by UniqueRecordIdentifier has been modified since the last time it was retrieved, 
the error (warning) CSSMERR_DL_RECORD_MODIFIED is returned but the requested attributes and data 
of the new record is returned. The caller should be advised that other attributes (or the data) might have 
changed that were not fetched from the DL with this call. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_DL_FIELD_SPECIFIED_MULTIPLE 
CSSMERR_DL_INCOMPATIBLE_FIELD_FORMAT 
CSSMERR_DL_INVALID_DB_HANDLE 
CSSMERR_DL_INVALID_FIELD_NAME 


CSSMERR_DL_INVALID_RECORDTYPE 
CSSMERR_DL_INVALID_RECORD_UID 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 
Functions for the CSSM API: 
CSSM_DL_Datalnset, CSSM_DL_DataGeFirst, CSSM_DL_DataGa@Nett 
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Functions for the DL SPI: 
CSSM_DL_Datalnset, CSSM_DL_DataGeFirst, CSSM_DL_DataGa@Nett 
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DL_DataGetNext 
NAME 
DL_DataGetN ext: CSSM_DL_DataGetNext - Get next data record (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 
CSSM_RETURN CSSMAPI CSSM_DL_DataGetNext 
(CSSM_DL_DB_HANDLE DLDBHandle, 


iy 


CSSM_HAND ResultsHandle, 
CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR Attributes, 
CSSM_DATA_PTR Data, 

CSSM_DB_UNIQUE_RECORD_PTR *Uniqueld) 

SPI: 
CSSM_RETURN CSSMDLI DL_DataGetNext 
(CSSM_DL_DB_ HANDLE DLDBHandle, 
CSSM_HANDLE ResultsHandle, 
CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR Attributes, 
CSSM_DATA_PTR Data, 
CSSM_DB_UNIQUE_RECORD_PTR *Uniqueld) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


DLDBHandle (input) 


The handle pair that describes the add-in data storage library module to be used to perform 
this function, and the open data store from which records were selected by the initiating 
query. 

Result sHandle (input) 


The handle identifying a set of records retrieved by a query executed by the 
CSSM_DL_DataGetFirst () function. 


Attributes (optional-input/output) 
If the Attributes structure pointer is NULL, no values are returned. 


Otherwise, the DataRecordType, NumberOfAttributes and AttributeData fields are read. 
AttributeData must bean array of NumberOfAttributes 
CSSM_DB_RECORD_ATTRIBUTE elements. Only the Info field of each element is used 
on input. The AttributeFormat field of the Info field is ignored on input. 


On output, aCSSM_DB RECORD ATTRIBUTE structure containing a list of all or the 
requested attribute values (subset) from the retrieved record. The SemanticInformation 
field is set. For each CSSM_DB_ATTRIBUTE_DATA contained in the attributeData 
array, the NumberOfValues field is set to reflect the size of the Value array which is 
allocated by the DL using the application specified allocators. Each CSSM_DATA in the 
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Value array will have it's Data field as a pointer to data allocated using the application 
specified allocators containing the attributes value, and have it's Length set tothe length of 
the value. 


All values for an attribute are returned (this could be 0). All fields in the Info field of the 
CSSM_DB_ATTRIBUTE_DATA are left unchanged except for the AttributeFormat field, 
which is set to reflect the schema. 


Data (optional-input/output) 


Data values contained in the referenced memory are ignored during processing and are 
overwritten with the retrieved opaque object. On output, aCSSM_DATA structure 
containing the opaque object stored in the retrieved record. If the pointer is data structure 
pointer is NULL, the opaque object is not returned. 


Uniqueld (output) 


If successful and (at least) a record satisfying the query has been found, then this parameter 
returns a pointer toa CSSM_UNIQUE_ RECORD PTR structure containing a unique 
identifier associated with the retrieved record. This unique identifier structure can be used 
in future references to this record using this DLDBHand1le pairing. It may not be valid for 
other DLHandles targeted to this DL module or to other DBHandles targeted to this data 
store. If there are no more records satisfying the query, then this pointer is NULL and 
CSSM_DL_DataGetNext () must return CSSM_DL_ENDOFDATA,; in this case a normal 
termination condition has occurred. The CSSM_DL_FreeUniqueRecord () must be used to 
deallocate this structure. 


DESCRIPTION 


This function returns the next data record referenced by the ResultsHandle. The Result sHandle references 
a set of records selected by an invocation of the DataGet First function. The Attributes parameter can specify 
a subset of the attributes to be returned. If Attributes specifies an attribute that is not defined in the 
database's meta-information, an error condition is returned. The record values are returned in the 
Attributes and Data parameters. The output buffers for the retrieved record are allocated by this function 
using the memory management functions provided during the module attach operation. The function also 
returns a unique record identifier for the return record. 


The data storage module supports one of two retrieval models: transactional or file system scan. The 
transactional model freezes the set of records to be retrieved at query initiation. The file system scan model 
selects from a potentially changing set of records during the retrieval process. The EndOfDataStore () 
function indicates when all matching records have been retrieved. The caller can determine which retrieval 
model is supported by examining the encapsulated product description for this data storage module. Once a 
user has finished using a certain query, it must call CSSM_DataAbortQuery () for releasing resources that 
CSSM uses. If all records satisfying the query have been retrieved, then query is automatically terminated. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 
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CSSMERR_DL_ENDOFDATA 

CSSMERR_DL_ FIELD SPECIFIED MULTIPLE 
CSSMERR_DL_INCOMPATIBLE FIELD FORMAT 
CSSMERR_DL_INVALTID_DB HANDLE 
CSSMERR_DL_ INVALID FIELD NAME 
CSSMERR_DL_INVALTID_RECORDTYPE 
CSSMERR_DL_INVALTID_RECORD_UID 
CSSMERR_DL_INVALID_ RESULTS _HANDLE 
SEE ALSO 

Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 
CSSM_DL_DataGeFirst, CSSM_DL_DataAbortQuery 
Functions for the DL SPI: 

DL_DataGetFirst, DL_DataAbortQuery 
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DL_Datalnsert 


NAME 
DL_Datalnsert: CSSM_DL_Datalnsert - Create new persistent data record (CDSA) 


SYNOPSIS 


#include <cssm.h> 


APTI: 

CSSM_RETURN CSSMAPI CSSM_DL_DataInsert 
(CSSM_DL_DB_HANDLE DLDBHandle, 
CSSM_DB_RECORDTYPE RecordType, 


const CSSM_DB_RECORD_ATTRIBUTE_DATA *Attributes, 


const CSSM_DATA *Data, 
CSSM_DB_UNIQUE_RECORD_PTR *Uniqueld) 


CSSM_RETURN CSSMDLI DL_DataInsert 
(CSSM_DL_DB_HANDLE DLDBHandle, 
CSSM_DB_RECORDTYPE RecordType, 
const CSSM_DB_RECORD_ATTRIBUTE_DATA *Attributes, 


const CSSM_DATA *Data, 
CSSM_DB_UNIQUE_RECORD_PTR *Uniqueld) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


DLDBHandle (input) 


The handle pair that describes the add-in data storage library module to be used to perform 


this function and the open data store in which to insert the new data record. 


RecordType (input) 
Indicates the type of data record being added to the data store. 


Attributes (input/optional) 


A list of structures containing the attribute values to be stored in that attribute, and the 
meta information (schema) describing those attributes. The list contains at most one entry 
per attribute in the specified record type. The specified AttributeFormat for each attribute 


must match that of the database schema, otherwise the error 


CSSMERR_DL_INCOMPATIBLE_FIELD_FORMAT is returned. If an attribute is of type 


CSSM_DB_ATTRIBUTE_FORMAT_STRING and the value specified for that string 


includes a null-terminator, then the length count in the CSSM_DATA structure containing 


the input string should include the terminating character. (If null-terminators are used, 


they should be used consistently when storing, searching, and retrieving the string value, 
otherwise selection predicates will not locate expected matches.) For those attributes that 
are not assigned values by the caller, the DL module may assume the values to be the empty 
set, or assume default values, or return an error. If the specified record type does not contain 


any attributes, this parameter must be NULL. 


Data (input/optional) 
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A pointer tothe CSSM_DATA structure which contains the opaque data object to be stored 
in the new data record. If the specified record type does not contain an opaque data object, 
this parameter must be NULL. 


Uniqueld (output) 


A pointer toa CSSM_DB_UNIQUE_RECORD_PTR containing a unique identifier 
associated with the new record. This unique identifier structure can be used in future 
references to this record during the current open data base session. The pointer will be set 
to NULL if the function fails. The cSSM_DL_FreeUniqueRecord() function must be used to 
deallocate this structure. 


DESCRIPTION 


This function creates a new persistent data record of the specified type by inserting it into the specified data 
store. The values contained in the new data record are specified by the Attributes and the Data. The 
attribute value list contains zero or more attribute values. The Attributes parameter also specifies a record 
type. This type must be the same as the type specified by the RecordType input parameter. The DL module 
may require initial values for the CSSM predefined attributes. The DL module can assume default values for 
any unspecified attribute values or can return an error condition when DLM-required attribute values are 
not specified by the caller. The Data is an opaque object to be stored in the new data record. 


If a primary key (concatination of all unique indexes in the relation) exists, the error 
CSSMERR_DL_INVALID_UNIQUE_INDEX_DATA is returned. The client should call 
CSSM_DL_DataGetFirst (), followed by CSSM_DL_DataModify() to changean existing record. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 

Errors are described in the CDSA Technical Standard. 
CSSMERR_DL_FIELD_SPECIFIED_MULTIPLE 
CSSMERR_DL_INCOMPATIBLE FIELD FORMAT 
CSSMERR_DL_INVALID_ FIELD NAME 
CSSMERR_DL_INVALTID_DB_ HANDLE 
CSSMERR_DL_INVALID_ PARSING MODULE 
CSSMERR_DL_INVALTID_RECORDTYPE 
CSSMERR_DL_INVALTID_RECORD_UID 
CSSMERR_DL_INVALID_UNIQUE_INDEX_DATA 
CSSMERR_DL_INVALID_ VALUE 
CSSMERR_DL_MISSING_VALUE 

SEE ALSO 

Books 


Inta CDSA Application Devdoper's Guide 


Online Help 
Functions for the CSSM API: 
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CSSM_DL_DataDdete 
Functions for the DL SPI: 
DL_DataDdete 
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DL_DataModify 


NAME 
DL_DataModify: CSSM_DL_DataModify - Modify persistent data record (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_DL_DataModify 
(CSSM_DL_DB_ HANDLE DLDBHandle, 

CSSM_DB_RECORDTYPE RecordType, 

CSSM_DB_UNIQUE_RECORD_PTR UniqueRecordIdentifier, 

const CSSM_DB_RECORD_ATTRIBUTE_DATA *AttributesToBeModi fied, 
const CSSM_DATA *DataToBeModified, 

CSSM_DB_MODIFY_MODE ModifyMode) 

SPI: 
CSSM_RETURN CSSMDLI DL_DataModify 

(CSSM_DL_DB_ HANDLE DLDBHandle, 

CSSM_DB_RECORDTYPE RecordType, 

CSSM_DB_UNIQUE_RECORD_PTR UniqueRecordIdentifier, 

const CSSM_DB_RECORD_ATTRIBUTE_DATA *AttributesToBeModi fied, 
const CSSM_DATA *DataToBeModified, 

CSSM_DB_MODIFY_MODE ModifyMode) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


DLDBHandle (input) 


The handle pair that describes the add-in data storage library module to be used to perform 
this function and the open data store to search for records satisfying the query. 


RecordType (input) 
Indicates the type of data record being modified. 
UniqueRecordIdenti fier (input/output) 


A pointer toa CSSM_DB_UNIQUE_RECORD containing a unique identifier associated 
with the record to modify. If the modification succeeds, the UniqueRecordIdentifier 
points toa CSSM_DB_ UNIQUE RECORD containing a unique identifier associated with 
the updated record. If the modification fails, the UniqueRecordIdentifier is not modified. 


Att ributesToBeModi fied (input/optional ) 


A list of structures containing the attribute values to be stored in that attribute and the 
meta information (schema) describing those attributes. The list contains at most one entry 
per attribute in the specified record type. The specified AttributeFormat for each attribute 
must match that of the database schema, otherwise the error 
CSSMERR_DL_INCOMPATIBLE_FIELD FORMAT is returned. If an attribute is of type 
CSSM_DB_ATTRIBUTE_FORMAT_STRING and the value specified for that string 
includes a null-terminator, then the length count in the CSSM_DATA structure containing 
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the input string should include the terminating character. (If null-terminators are used, 
they should be used consistently when storing, searching, and retrieving the string value, 
otherwise selection predicates will not locate expected matches.) Each attribute specified is 
modified according to the value of Modi fyMode (see table in the DESCRIPTION section of this 
definition). Those attributes that are not specified as part of this parameter remain 
unchanged. If the AttributesToBeModified parameter is NULL, no attribute modification 
occurs. 


Dat aToBeModi fied (input/optional ) 


A pointer to the CSSM_DATA structure which contains the opaque data object to be stored 
in the data record. If this parameter is NULL, no Data modification occurs. 


ModifyMode (input) 


A CSSM_DB_MODIFY_MODE value indicating the type of modification to be performed on 
the record attributes identified by AttributesToBeModi fied. If no attributes are specified, 
then this value must be CSSM_DB_MODIFY_ATTRIBUTE_NONE. 


DESCRIPTION 


This function modifies the persistent data record identified by the UniqueRecordIdentifier. The 
modifications are specified by the Attributes and Data parameters. The ModifyMode indicates how the 
attributes are to be updated. The Modi fyMode has no affect on updating the data blob contained in the record. 
If the data blob is the only record attribute being updated by this function call, then the modification mode 
must be 0. The current modification modes behave as follows: 


ModifyMode Value Function Behavior 
CSSM_DB_MODIFY_ATTRIBUTE_NONE No Attributes are being updated. 
CSSM_DB_MODIFY_ATTRIBUTE_ADD The specified values are added to the set of current 


values for each attribute. If 0 values are specified 
then the error 
CSSMERR_DL_INVALID_MODIFY_MODE is 
returned. If a DL does not support multiple values 
per attribute, the error 
CSSMERR_DL_MULTIPLE_VALUES UNSUPPO 
RTED is returned. 


CSSM_DB_MODIFY_ATTRIBUTE_DELETE The specified values are removed from the set of 
current values for each attribute. If 0 values are 
specified then all values are deleted or the 
attributes value is replaced with the default for this 
attribute. If a DL does not support multiple values 
per attribute, the error 
CSSMERR_DL_MULTIPLE_VALUES UNSUPPO 
RTED is returned. 
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CSSM_DB_MODIFY_ATTRIBUTE_ REPLACE The values for each attribute are replaced with the 
specified set of values for each attribute. If no 
values are specified then all values are deleted or 
the attributes value is replaced with the default for 
this attribute. If a DL does not support multiple 
values per attribute, the error 
CSSMERR_DL_MULTIPLE_VALUES UNSUPPO 
RTED is returned when more than 1 valueis 
specified. 


If the attribute lists specifies an attribute that is not defined in the database's meta-information, an error 
condition is returned. For each attribute-value pair, the value replaces the corresponding attribute value in 
the record. If a data value is specified, the record's data value is replaced with the specified value. A record's 
data value or attribute values can be set to NULL or zero to represent deletion or the lack of a known value. 


If the record referenced by UniqueRecordIdentifier has been modified since the last time it was updated, 
the error CSSMERR_DL_STALE_UNIQUE_RECORD is returned and no modification takes place. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 

Errors are described in the CDSA Technical Standard. 
CSSMERR_DL_FIELD_SPECIFIED_MULTIPLE 
CSSMERR_DL_INCOMPATIBLE_FIELD_FORMAT 
CSSMERR_DL_INVALID_DB_HANDLE 
CSSMERR_DL_INVALID_FIELD_NAME 
CSSMERR_DL_INVALID_MODIFY_MODE 
CSSMERR_DL_INVALID_RECORDTYPE 
CSSMERR_DL_INVALID_RECORD_UID 
CSSMERR_DL_INVALID_UNIQUE_INDEX_DATA 
CSSMERR_DL_INVALID_VALUE 
CSSMERR_DL_MULTIPLE_VALUES_UNSUPPORTED 
CSSMERR_DL_STALE_UNIQUE_RECORD 

SEE ALSO 

Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 
CSSM_DL_Datalnset, CSSM_DL_DataDdete 
Functions for the DL SPI: 

DL_Datalnsert, DL_DataDddte 
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DL_DbClose 


NAME 
DL_DbClose: CSSM_DL_DbClose - Close open data store (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_DL_DbClose 
(CSSM_DL_DB_ HANDLE DLDBHandle) 

SPL: 
CSSM_RETURN CSSMDLI DL_DbClose 
(CSSM_DL_DB_ HANDLE DLDBHandle) 


LIBRARY 


Common Security Services Manager library (cdsa$Sincssm300_shr.exe) 


PARAMETERS 


DLDBHandle (input) 


A handle structure containing the DL handle for the attached DL module and the DB 
handle for an open data store managed by the DL. This specifies the open data store to be 
closed. 


DESCRIPTION 


This function closes an open data store. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_DL_INVALID_DB_HANDLE 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 
Functions for the CSSM API: 
CSSM_DL_DbOpen 
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Functions for the DL SPI: 
DL_DbOpen 
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DL_DbCreate 


NAME 
DL_DbCreate: CSSM_DL_DbCreate - Create and open new data store (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_DL_DbCreate 
(CSSM_DL_HANDLE DLHandle, 
const char *DbName, 
const CSSM_NET_ADDRESS *DbLocation, 
const CSSM_DBINFO *DBInfo, 
CSSM_DB_ACCESS_TYPE AccessRequest, 
const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry, 
const void *OpenParameters, 

CSSM_DB_ HANDLE *DbHandle) 
SPI: 
CSSM_RETURN CSSMDLI DL_DbCreate 
(CSSM_DL_HANDLE DLHandle, 

const char *DbName, 
const CSSM_NET_ADDRESS *DbLocation, 
const CSSM_DBINFO *DBInfo, 
CSSM_DB_ACCESS_TYPE AccessRequest, 

const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry, 
const void *OpenParameters, 

CSSM_DB_ HANDLE *DbHandle) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


DLHandle (input) 


The handle that describes the add-in data storage library module used to perform this 
function. 


DbName (input) 
The logical name for the new data store. 
DbLocation (input/optional) 


A pointer to a network address directly or indirectly identifying the location of the storage 
service process. If the input is NULL, the module can assume a default storage service 
process location. I f the DoName does not distinguish the storage service process, the service 
cannot be performed and the operation fails. 


DBInfo (input) 


A pointer to a structure describing the format/schema of each record type that will be stored 
in the new data store. 


AccessRequest (input) 
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An indicator of the requested access mode for the data store, such as read-only or 
read-write. 


CredAndAclEntry (input/optional) 


A structure containing one or more credentials authorized for creating a data base and the 
prototype ACL entry that will control future use of the newly created key. The credentials 
and ACL entry prototype can be presented as immediate values or callback functions can be 
provided for use by the DL to acquire the credentials and/or the ACL entry interactively. If 
the DL provides public access for creating a data base, then the credentials can be NULL. If 
the DL defines a default initial ACL entry for the new data base, then the ACL entry 
prototype can be an empty list. 


OpenParameters (input/optional) 
A pointer toa module-specific set of parameters required to open the data store. 
DbHandle (output) 


The handle to the newly created and open data store. The value will be set to 
CSSM_INVALID_HANDLE if the function fails. 


DESCRIPTION 


This function creates and opens a new data store. The name of the new data store is specified by the input 
parameter DbName. The record schema for the data store is specified in the DBINFO structure. If any 
RecordType defined in the DBINFO structure does not have an associated parsing module, then the 
ModuleSubserviceUid specified for that record type must be zero. 


The newly created data store is opened under the specified access mode. | f user authentication credentials are 
required, they must be provided. Also, additional open parameters may be required and are supplied in 
OpenParameters. If user authentication credentials are required, they must be provided. 


Authorization policy can restrict the set of callers who can create a new resource. In this case, the caller must 
present a set of access credentials for authorization. Upon successfully authenticating the credentials, the 
template that verified the presented samples identifies the ACL entry that will be used in the authorization 
computation. If the caller is authorized, the new resource is created. 


The caller must provide an initial ACL entry to be associated with the newly created resource. This entry is 
used to control future access to the new resource and (since the subject is deemed to be the "Owner") exercise 
control over its associated ACL. The caller can specify the following items for initializing an ACL entry: 


Subject 


A CSSM LIST structure, containing the type of the subject and a template value that can 
be used to verify samples that are presented in credentials when resource access is 
requested. 


Delegation flag 


A value indicating whether the Subject can delegate the permissions recorded in the 
AuthorizationTag. (This item only applies to public key subjects). 


Authorization tag 

The set of permissions that are granted to the Subject. 
Validity period 

The start time and the stop time for which the ACL entry is valid. 
ACL entry tag 
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A user-defined string value associated with the ACL entry. 


The service provider can modify the caller-provided initial ACL entry to conform to any 
innate resource-access policy that the service provider may be required to enforce. If the 
initial ACL entry provided by the caller contains values or permissions that are not 
supported by the service provider, then the service provider can modify the initial ACL 
appropriately or can fail the request to create the new resource. Service providers list their 
supported AuthorizationTag values in their Module Directory Services primary record. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 

Errors are described in the CDSA Technical Standard. 
CSSMERR_DL_DATASTORE_ALREADY_EXISTS 
CSSMERR_DL_FIELD_SPECIFIED_MULTIPLE 
CSSMERR_DL_INCOMPATIBLE FIELD FORMAT 
CSSMERR_DL_INVALID_ACCESS_REQUEST 
CSSMERR_DL_INVALID_DB LOCATION 
CSSMERR_DL_INVALID_DB_ NAME 
CSSMERR_DL_INVALID_ FIELD NAM 
CSSMERR_DL_INVALID_OPEN PARAMETERS 
CSSMERR_DL_ INVALID PARSING _MODULE 
CSSMERR_DL_INVALID_RECORDTYPE 
CSSMERR_DL_INVALID_RECORD_INDEX 
CSSMERR_DL_UNSUPPORTED_FIELD_ FORMA 
CSSMERR_DL_UNSUPPORTED_INDEX_INFO 
CSSMERR_DL_UNSUPPORTED_LOCALITY 
CSSMERR_DL_UNSUPPORTED_NUM_ATTRIBUTES 
CSSMERR_DL_UNSUPPORTED_NUM_INDEXES 
CSSMERR_DL_ UNSUPPORTED _NUM_RECORDTYPES 
CSSMERR_DL_UNSUPPORTED_RECORDTYPE 
SEE ALSO 

Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 

CSSM_DL_DbOpen, CSSM_DL_DbClose CSSM_DL_DbDdete 
Functions for the DL SPI: 

DL_DbOpen, DL_DbClose DL_DbDedete 
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DL_DbDelete 
NAME 
DL_DbDelete: CSSM_DL_DbDelete - Delete all records (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 


CSSM_R 


(CSSM_ 
const 
const 
const 
SPI: 


CSSM_R 


(CSSM_ 
const 
const 


const 


ETURN CSSMAPI CSSM_DL_DbDelete 
__HANDLI 


EF DLHandle, 


DL_H 


| NET. 


*DbName, 
ADDRESS *DbLocation, 


ESS_CREDENTIALS *AccessCred) 


ETURN CSSMDLI DL_DbDelete 
ANDLI 


EF DLHandle, 


char 


CSSM_| 
CSSM_. 


*DbName, 


NET_. 


ADDRESS *DbLocation, 


ACC] 


ESS CREDENTIALS *AccessCred) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


DLHandle (input) 


DbName (input) 


The handle that describes the add-in data storage library module to be used to perform this 
function. 


A pointer to the string containing the logical name of the data store. 


DbLocation (input/optional) 


A pointer to a network address directly or indirectly identifying the location of the storage 
service process. If the input is NULL, the module can assume a default storage service 
process location. I f the DpoName does not distinguish the storage service process, the service 
cannot be performed and the operation fails. 


AccessCred (input/optional) 
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A pointer to the set of one or more credentials being presented for authentication by the 
caller. These credentials are required to obtain access to the specified data store. The 
credentials structure can contain multiple types of credentials, as required for multi-factor 
authentication. The credential data can be an immediate value, such as a passphrase, PIN, 
certificate, or template of user-specific data, or the caller can specify a callback function the 
DL can use to obtain one or more credentials. The required set of credentials to access a 
particular data store is defined by the DbInfo record containing meta-data for the specified 
data store. If credentials are not required to access the specified data store, then this field 
can be NULL. 


DESCRIPTION 


This function deletes all records from the specified data store and removes all state information associated 
with that data store. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_DL_DATASTORE_DOESNOT_EXIST 
CSSMERR_DL_DATASTORE_IS_OPEN 
CSSMERR_DL_INVALID_DB_LOCATIO 


CSSMERR_DL_INVALID_DB_NAME 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 

CSSM_DL_DbCreate CSSM_DL_DbOpen, CSSM_DL_DbClose 
Functions for the DL SPI: 

DL_DbCreate, DL_DbOpen, DL_DbClose 
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DL_DbOpen 
NAME 
DL_DbOpen: CSSM_DL_DbOpen - Open a data store (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_DL_DbOpen 
(CSSM_DL_HANDLE DLHandle, 
const char *DbName, 
const CSSM_NET_ADDRESS *DbLocation, 
CSSM_DB_ACCESS_TYPE AccessRequest, 


const CSSM_ACCESS_CREDENTIALS *AccessCred, 
const void *OpenParameters, 

CSSM_DB_ HANDLE *DbHandle) 

SPI: 
CSSM_RETURN CSSMDLI DL_DbOpen 
(CSSM_DL_HANDLE DLHandle, 
const char *DbName, 
const CSSM_NET_ADDRESS *DbLocation, 
CSSM_DB_ACCESS_TYPE AccessRequest, 
const CSSM_ACCESS_ CREDENTIALS *AccessCred, 


const void *OpenParameters, 
CSSM_DB_HANDLE *DbHandle) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


DLHandle (input) 


The handle that describes the add-in data storage library module to be used to perform this 
function. 


DbName (input) 
A pointer to the string containing the logical name of the data store. 
DbLocation (input/optional) 


A pointer to a network address directly or indirectly identifying the location of the storage 
service process. If the input is NULL, the module can determine a storage service process 
and its location based on the DbName (for existing data stores) or can assume a default 
storage service process location. I f the DoName does not distinguish the storage service 
process, the service cannot be performed and the operation fails. 


AccessRequest (input) 


An indicator of the requested access mode for the data store, such as read-only or 
read-write. 


AccessCred (input/optional) 
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A pointer to the set of one or more credentials being presented for authentication by the 
caller. These credentials are required to obtain access to the specified data store. The 
credentials structure can contain multiple types of credentials, as required for multi-factor 
authentication. The credential data can be an immediate value, such as a passphrase, PIN, 
certificate, or template of user-specific data, or the caller can specify a callback function the 
DL can use to obtain one or more credentials. The required set of credentials to access a 
particular data store is defined by the DbInfo record containing meta-data for the specified 
data store. If credentials are not required to access the specified data store, then this field 
can be NULL. 


OpenParameters (input/optional) 
A pointer to a module-specific set of parameters required to open the data store. 
DbHandle (output) 


The handle to the opened data store. The value will beset to CSSM_INVALID_HANDLE if 
the function fails. 


DESCRIPTION 


This function opens the data store with the specified logical name under the specified access mode. | f user 
authentication credentials are required, they must be provided. Also, additional open parameters may be 
required to open a given data store, and are supplied in the OpenParameters. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_DL_DB_LOCKED 
CSSMERR_DL_INVALID_ACCESS_REQUEST 
CSSMERR_DL_INVALID_DB_LOCATIO 
CSSMERR_DL_INVALID_DB_NAME 


CSSMERR_DL_DATASTORE_DOESNOT_EXIST 
CSSMERR_DL_INVALID_PARSING_MODULE 
CSSMERR_DL_INVALID_OPEN_PARAMETERS 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 
CSSM_DL_DbClose 
Functions for the DL SPI: 
DL_DbClose 
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DL_DestroyRelation 


NAME 
DL_DestroyRelation: CSSM_DL_DestroyRelation - Destroy an existing relation (CDSA) 


SYNOPSIS 


#include <cssm.h> 


APTI: 

CSSM_RETURN CSSMAPI CSSM_DL_DestroyRelation 
(CSSM_DL_DB_HANDLE DLDBHandle, 
CSSM_DB_RECORDTYPE RelationID) 
SPI: 
CSSM_RETURN CSSMDLI DL_DestroyRelation 
(CSSM_DL_DB_HANDLE DLDBHandle, 


CSSM_DB_RECORDTYPE RelationID) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


DLDBHandle (input) 


The handle pair that describes the add-in data storage library module to be used to perform 
this function and the open data store from which to delete the relation record. 


RelationID (input) 


Indicates the type of relation record being deleted from the data store. 


DESCRIPTION 


This function destroys an existing relation of the specified type by removing its entry from the specified data 
store. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_DL_INVALID_DB_HANDLE 
CSSMERR_DL_INVALID_RECORDTYPE 
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SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 
CSSM_DL_CreateRedlation 
Functions for the DL SPI: 
DL_CreateR dation 
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DL_FreeNameList 


NAME 
DL_FreeNameList: CSSM_DL_FreeNameList - Free the list of the logical data store names (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_DL_FreeNameList 
(CSSM_DL_HANDLE DLHandle, 
CSSM_NAME_LIST_PTR NameList) 

SPI: 
CSSM_RETURN CSSMDLI DL_FreeNameList 
(CSSM_DL_HANDLE DLHandle, 
CSSM_NAME_LIST_PTR NameList) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


DLHandle (input) 


The handle that describes the add-in data storage library module to be used to perform this 
function. 


NameList (input) 
A pointer tothe CSSM_NAME LIST. 


DESCRIPTION 


This function frees the list of the logical data store names that was returned by cSSM_DL_GetDbNames. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


None specific to this call. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


312 


Online Help 


Functions for the CSSM API: 


CSSM_DL_Ga&DbNames 
Functions for the DL SPI: 
DL_Ga&DbNames 
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DL_FreeUniqueRecord 


NAME 
DL_FreeUniqueRecord: CSSM_DL_FreeUniqueRecord - Free data store memory (CDSA) 


SYNOPSIS 


#include <cssm.h> 


APTI: 

CSSM_RETURN CSSMAPI CSSM_DL_FreeUniqueRecord 
(CSSM_DL_DB_HANDLE DLDBHandle, 
CSSM_DB_UNIQUE_RECORD_PTR UniqueRecord) 

SPI: 
CSSM_RETURN CSSMDLI DL_FreeUniqueRecord 
(CSSM_DL_DB_HANDLE DLDBHandle, 
CSSM_DB_UNIQUE_RECORD_PTR UniqueRecord) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


DLDBHandle (input) 


The handle pair that describes the add-in data storage library module to be used to perform 
this function and the open data store from which the UniqueRecord identifier was assigned. 


UniqueRecord(input) 


The pointer to the memory that describes the data store unique record structure. 


DESCRIPTION 


This function frees the memory associated with the data store unique record structure. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_DL_INVALID_DB_HANDLE 
CSSMERR_DL_INVALID_RECORD_UID 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 
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Online Help 

Functions for the CSSM API: 

CSSM_DL_Datalnsert, CSSM_DL_DataGeFirst, CSSM_DL_DataGa&Nett 
Functions for the DL SPI: 

DL_Datalnsert, DL_DataGeFirst, DL_DataGa&Next 
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DL_GetDbAcl 


NAME 
DL_GetDbAd: CSSM_DL_GetDbAcl - Get ACL description (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 
CSSM_RETURN CSSMAPI CSSM_DL_GetDbAcl1 
(CSSM_DL_DB_ HANDLE DLDBHandle, 

const CSSM_STRING *SelectionTag, 
uint32 *NumberOfAcliInfos, 


CSSM_ACL_ENTRY_INFO_PTR *AcliInfos) 


SPI: 
CSSM_RETURN CSSMDLI DL_GetDbAcl 
(CSSM_DL_DB_ HANDLE DLDBHandle, 


const CSSM_STRING *SelectionTag, 
uint32 *NumberOfAcliInfos, 
CSSM_ACL_ENTRY_INFO_PTR *AclInfos) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


DLDBHandle (input) 


The handle pair that identifies the Data Storage service provider to perform this operation 
and the target data store whose associated ACL entries are scanned and returned. 


Select ionTag (input/optional) 


A CSSM_STRING value matching the user-defined tag value associated with one or more 
ACL entries for the target data base. To retrieve a description of all ACL entries for the 
target data base, this parameter must be NULL. 


NumberOfAclInfos (output) 


The number of entries in the AclInfos array. If no ACL entry descriptions are returned, 
this value is zero. 


AclInfos (output) 


An array of CSSM_ACL_ENTRY_INFO structures. The unique handle contained in each 
structure can be used during the current attach session to reference the ACL entry for 
editing. The structure is allocated by the service provider and must be released by the caller 
when the structure is no longer needed. If no ACL entry descriptions are returned, this 
valueis NULL. 


DESCRIPTION 


This function returns a description of zero or more ACL entries managed by the data storage service provider 
module and associated with the target database identified by DLDBHandle.DBHandle. The optional input 
SelectionTag restricts the returned descriptions to those ACL entries with a matching Ent ryTag value. Ifa 


316 


Select ionTag value is specified and no matches are found, zero descriptions are returned. If no 
SelectionTag is specified, a description of all ACL entries associated with the target data base are returned 
by this function. 


Each AcliInfo structure contains: 


e Public contents of an ACL entry 


e ACL EntryHandle, which is a unique value defined and managed by the service provider 


The public ACL entry information returned by this function includes: 
The subject type 


A CSSM_LIST structure containing one element identifying the type of subject stored in the 
ACL entry. 


Delegation flag 


A CSSM_BOOL value indicating whether the subject can delegate the permissions recorded 
in Authorization. 


Authorization array 


A CSSM_AUTHORIZATIONGROUP structure defining the set of operations for which 
permission is granted to the Subject. 


Validity period 


A CSSM_ACL_VALIDITY_PERIOD structure containing two elements, the start time and 
the stop time for which the ACL entry is valid. 


ACL entry tag 
A CSSM_STRING containing a user-defined value associated with the ACL entry. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_DL_INVALID_DB_HANDLE 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 
CSSM_DL_ChangeDbAcl 
Functions for the DL SPI: 
DL_ChangeDbAcl 
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DL_GetDbNameF romHandle 


NAME 
DL_GetDbNameF romH andle: CSSM_DL_GetDbNameF romH andle - Get data source name (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_DL_GetDbNameFromHandle 
(CSSM_DL_DB_ HANDLE DLDBHandle, 

char **DbName) 
SPI: 
CSSM_RETURN CSSMDLI DL_GetDbNameFromHandle 
(CSSM_DL_DB_ HANDLE DLDBHandle, 

char **DbName) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


DLDBHandle (input) 


The handle pair that identifies the add-in data storage library module and the open data 
store whose name should be retrieved. 


DbName (output) 


Returns a zero terminated string which contains a data storename. The memory is 
allocated by the service provider and must be deallocated by the application. 


DESCRIPTION 


This function retrieves the data source name corresponding to an opened data store handle. 


RETURN VALUE 
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_DL_INVALID_DB_HANDLE 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 
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Online Help 


Functions for the CSSM API: 


CSSM_DL_Ga&DbNames 
Functions for the DL SPI: 
DL_Ga&DbNames 
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DL_GetDbNames 


NAME 
DL_GetDbNames: CSSM_DL_GetDbNames - Get list of logical data store names (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_DL_GetDbNames 
(CSSM_DL_HANDLE DLHandle, 
CSSM_NAME_LIST_PTR *NameList) 

SPI: 
CSSM_RETURN CSSMDLI DL_GetDbNames 
(CSSM_DL_HANDLE DLHandle, 
CSSM_NAME_LIST_PTR *NameList) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


DLHandle (input) 


The handle that describes the add-in data storage library module to be used to perform this 
function. 


NameList (output) 
Returns alist of data storenames in aCSSM_ NAME _LIST_PTR structure. 


DESCRIPTION 


This function returns the list of logical data store names for all data stores that are known by and accessible 
to the specified DL module. This list also includes the number of data store names in the return list. 


The CSSM_DL_FreeNameList () function must be called to deallocate memory containing the list. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


None specific to this call. 
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SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 
CSSM_DL_Ga&DbNameFromHandle CSSM_DL_FreeNameist 
Functions for the DL SPI: 

DL_Ge&DbNameFromHandle, DL_FreeN ame ist 
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DL_GetDbOwner 


NAME 
DL_GetDbOwner: CSSM_DL_GetDbOwner - Get data base owner (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_DL_GetDbOwner 
(CSSM_DL_DB_ HANDLE DLDBHandle, 
CSSM_ACL_OWNER_PROTOTYPE_PTR Owner) 
SPI: 
CSSM_RETURN CSSMDLI DL_GetDbOwner 
(CSSM_DL_DB_ HANDLE DLDBHandle, 
CSSM_ACL_OWNER_PROTOTYPE_PTR Owner) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETER 


DLDBHandle (input) 


The handle pair that describes the data storage library module to be used to perform this 
function, and the open data store whose associated Owner is to be retrieved. 


Owner (output) 
A CSSM_ACL_OWNER_PROTOTYPE describing the current Owner of the Data Base. 


DESCRIPTION 
This function returns a CSSM_ACL_OWNER_PROTOTYPE describing the current Owner of the Data Base. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_DL_INVALID_DB_HANDLE 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 
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Online Help 


Functions for the CSSM API: 


CSSM_DL_ChangeDbOwne 
Functions for the DL SPI: 
DL_ChangeDbOwner 
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DL_PassThrough 


NAME 
DL_PassThrough: CSSM_DL_PassThrough - Extend data storage module functionality (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_DL_PassThrough 
(CSSM_DL_DB_HANDLE DLDBHandle, 

uint32 PassThroughId, 

const void *InputParams, 

void **OutputParam) 

SPI: 
CSSM_RETURN CSSMDLI DL_PassThrough 
(CSSM_DL_DB_HANDLE DLDBHandle, 
uint32 PassThroughId, 

const void *InputParams, 

void **OutputParam) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


DLDBHandle (input) 


The handle pair that describes the add-in data storage library module to be used to perform 
this function and the open data store upon which the function is to be performed. 


PassThroughId (input) 
An identifier assigned by a DL module to indicate the exported function to be performed. 
InputParams (input) 


A pointer to a module implementation-specific structure containing parameters to be 
interpreted in a function-specific manner by the requested DL module. 


OutputParams (output) 


A pointer to a module, implementation-specific structure containing the output data. The 
service provider will allocate the memory for this structure. The application should free the 
memory for the structure. 


DESCRIPTION 


This function allows applications to call data storage library module-specific operations that have been 
exported. Such operations may include queries or services that are specific to the domain represented by a DL 
module. 
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RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 


indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_DL_INVALID_DB_HANDLE 
CSSMERR_DL_INVALID_PASSTHROUGH_ID 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 
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EncryptData 


NAME 
EncryptData: CSSM_EncryptData, CSP_EncryptData - Encrypts all buffer data (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_EncryptData 
(CSSM_CC_HANDLE CCHandle, 

const CSSM_DATA *ClearBufs, 

uint32 ClearBufCount, 

CSSM_DATA_PTR CipherBufs, 

uint32 CipherBufCount, 

uint32 *bytesEncrypted, 
CSSM_DATA_PTR RemData) 

SPL 
CSSM_RETURN CSSMCSPI CSP_EncryptData 
(CSSM_CSP_HANDLE CSPHandle, 
CSSM_CC_HANDLE CCHandle, 

const CSSM_CONTEXT *Context, 

const CSSM_DATA *ClearBufs, 

uint32 ClearBufCount, 

CSSM_DATA_PTR CipherBufs, 

uint32 CipherBufCount, 

uint32 *bytesEncrypted, 
CSSM_DATA_PTR RemData, 
CSSM_PRIVILEGE Privilege) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


API PARAMETERS 


CCHandle (input) 


The handle that describes the context of this cryptographic operation used to link to the 
CSP-managed information. 


ClearBufs (input) 
A pointer toa vector of CSSM_DATA structures that contain the data to be operated on. 


ClearBufCount (input) 
The number of ClearBufs. 
CipherBufs (output) 


A pointer toa vector of CSSM_DATA structures that contain the results of the operation on 
the data. 


CipherBufCount (input) 


The number of CipherBufs. 
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bytesEncrypted (output) 


A pointer to uint32 for the size of the encrypted data in bytes. 


RemData (output) 


A pointer to the CSSM_DATA structure for the remaining cipher text if there is not enough 
buffer space available in the output data structures. 


SPI PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform calls to CSSM for the memory functions managed by CSSM. 


Context (input) 
Pointer to CSSM_CONTEXT structure that describes the attributes with this context. 
Privilege (input) 


The export privilege to be applied during the cryptographic operation. This parameter is 
forwarded to the CSP after CSSM verifies the caller and service provider privilege set 
includes the specified PRIVILEGE. 


DESCRIPTION 


This function encrypts all data contained in the set of input buffers using information in the context. The 
CSSM_QuerySize() function can be used to estimate the output buffer size required. The minimum number of 
buffers required to contain the resulting cipher text is produced as output. | f the cipher text result does not fit 
within the set of output buffers, the remaining cipher text is returned in the single output buffer RemData. 


The CSP can require that the cryptographic context include access credentials for authentication and 
authorization checks when using a private key or a secret key. 


NOTES FOR API 


The output is returned to the caller either by filling the caller-specified buffer or by using the application's 
declared memory allocation functions to allocate buffer space. To specify a specific, preallocated output buffer, 
the caller must provide an array of oneor more CSSM_DATA structures, each containing a Length field value 
greater than zero and a non-NULL data pointer field value. To specify automatic output buffer allocation by 
the CSP, the caller must provide an array of one or more CSSM_DATA structures, each containing a Length 
field value equal to zero and a NULL Data pointer field value. The application is always responsible for 
deallocating the memory when it is no longer needed. | n-place encryption can be done by supplying the same 
input and output buffers. 


NOTES FOR SPI 


The output is returned to the caller as specified in Buffer Management for Cryptographic Services. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 
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ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CSP_BLOCK_SIZE_MISMATCH 
CSSMERR_CSP_OUTPUT_LENGTH_ERROR 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 


Functions for the CSSM API: 


CSSM_QuerySize, CSSM_DecryptData, CSSM_EncryptDatal nit, CSSM_EncryptDataU pdate 
CSSM_EncryptDataFinal, CSSM_EncryptDataP, CSSM_EncryptDatalnitP, CSSM_DecryptP, 
CSSM_DecryptDatal nitP 


Functions for the CSP SPI: 


CSP_QuerySize CSP_DecryptData, CSP_EncryptDatal nit, CSP_EncryptDataU pdate, 
CSP_EncryptDataF inal 
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EncryptDataF inal 


NAME 
EncryptDataF inal: CSSM_EncryptDataFinal, CSP_EncryptDataFinal - Finalize staged encryption 
process (CDSA) 

SYNOPSIS 

#include <cssm.h> 

API: 

CSSM_RETURN CSSMAPI CSSM_EncryptDataFinal 


(CSSM_CC_HANDLE CCHandle, 
CSSM_DATA_PTR RemData) 
SPI: 
CSSM_RETURN CSSMCSPI CSP_EncryptDataFinal 
(CSSM_CSP_HANDLE CSPHandle, 
CSSM_CC_HANDLE CCHandle, 

CSSM_DATA_PTR RemData) 


LIBRARY 


Common Security Services M anager library (cdsa$incssm300_shr.exe) 


API PARAMETERS 


CCHandle (input) 


The handle that describes the context of this cryptographic operation used to link to the 
CSP-managed information. 


RemData (output) 


A pointer tothe CSSM_DATA structure for the last encrypted block containing padded 
data, if necessary. 


SPI PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform calls to CSSM for the memory functions managed by CSSM. 


DESCRIPTION 


This function finalizes the staged encryption process by returning any remaining cipher text not returned in 
the previous staged encryption call. The cipher text is returned in a single buffer. 


NOTES FOR API 


The output is returned to the caller either by filling the caller-specified buffer or by using the application's 
declared memory allocation functions to allocate buffer space. To specify a specific, preallocated output buffer, 
the caller must provide an array of one or more CSSM_DATA structures, each containing a Length field value 
greater than zero and a non-NULL data pointer field value. To specify automatic output buffer allocation by 


329 


the CSP, the caller must provide an array of one or more CSSM_DATA structures, each containing a Length 
field value equal to zero and a NULL data pointer field value. The application is always responsible for 
deallocating the memory when it is no longer needed. 


NOTES FOR SPI 


The output is returned to the caller as specified in Buffer Management for Cryptographic Services. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CSP_BLOCK_SIZE_MISMATCH 
CSSMERR_CSP_OUTPUT_LENGTH_ERROR 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 
Functions for the CSSM API: 


CSSM_QuerySize, CSSM_DecryptData, CSSM_EncryptDatal nit, CSSM_EncryptDataU pdate 
CSSM_EncryptDataFinal, CSSM_EncryptDataP, CSSM_EncryptDatalnitP, CSSM_DecryptP, 
CSSM_DecryptDatal nitP 


Functions for the CSP SPI: 
CSP_EncryptData, CSP_EncryptDatal nit, CSP_EncryptDataU pdate 
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EncryptDatal nit 


NAME 


EncryptDatal nit: CSSM_EncryptDatal nit, CSP_EncryptDatal nit - Initialize the staged encrypt 
funciton (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_EncryptDataInit 
(CSSM_CC_HANDLE CCHandle) 

SPI: 
CSSM_RETURN CSSMCSPI CSP_EncryptDataInit 
(CSSM_CSP_HANDLE CSPHandle, 
CSSM_CC_HANDLE CCHandle, 

const CSSM_CONTEXT *Context, 
CSSM_PRIVILEGE Privilege) 


LIBRARY 


Common Security Services M anager library (cdsa$incssm300_shr.exe) 


API PARAMETERS 


CCHandle (input) 


The handle that describes the context of this cryptographic operation used to link to the 
CSP-managed information. 


SPI PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform calls to CSSM for the memory functions managed by CSSM. 


Context (input) 
Pointer to CSSM_CONTEXT structure that describes the attributes with this context. 
Privilege (input) 


The export privilege to be applied during the cryptographic operation. This parameter is 
forwarded to the CSP after CSSM verifies the caller and service provider privilege set 
includes the specified PRIVILEGE. 


DESCRIPTION 


This function initializes the staged encrypt function. There may be algorithm-specific and token-specific rules 
restricting the lengths of data following data update calls making use of these parameters. 


The CSP can require that the cryptographic context include access credentials for authentication and 
authorization checks when using a private key or a secret key. 
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RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


None specific to this call. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 


Functions for the CSSM API: 


CSSM_QuerySize, CSSM_DecryptData, CSSM_EncryptDatal nit, CSSM_EncryptDataU pdate 
CSSM_EncryptDataFinal, CSSM_EncryptDataP, CSSM_EncryptDatalnitP, CSSM_DecryptP, 
CSSM_DecryptDatal nitP 


Functions for the CSP SPI: 


CSP_QuerySize CSP_DecryptData, CSP_EncryptDatal nit, CSP_EncryptDataU pdate, 
CSP_EncryptDataF inal 
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EncryptDatal nitP 
NAME 
EncryptDatal nitP - Initialize the staged encrypt function with privilege (CDSA) 


SYNOPSIS 


# include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_EncryptDataInitP 
(CSSM_CC_HANDLE CCHandle, 
CSSM_PRIVILEGE Privilege) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 
Privilege (input) 

The privilege to be applied during the cryptographic operation. 
See CSSM_EncryptDatal nit for other parameters. 


DESCRIPTION 


This function is similar to CSSM_EncryptDataInit (). It also accepts a USEE tag as a privilege request 
parameter. CSSM checks that either its privilege set or the application's privilege set (if the application is 
signed) includes the tag. If the tag is found and the service provider privilege set indicates that it is 
supported, the tag is forwarded to the service provider. 


For staged operations using privilege initialization functions CSSM_EncryptDataInitP (), the completion 
functions CSSM_EncryptDataUpdate() and CSSM_EncryptDataFinalize() are used. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


None specific to this call. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 
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Online Help 


Functions: CSSM_DecryptData, CSSM_EncryptDatal nit, CSSM_EncryptDataU pdate, 
CSSM_EncryptDataFinal, CSSM_EncryptDataP, CSSM_EncryptDatalnitP, CSSM_DecryptP, 
CSSM_DecryptDatal nitP, CSSM_QuerySize 
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EncryptDataP 
NAME 
EncryptDataP - Encrypt data with privilege (CDSA) 


SYNOPSIS 


# include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_EncryptDataP 
(CSSM_CC_HANDLE CCHandle, 

const CSSM_DATA *ClearBufs, 

uint32 ClearBufCount, 

CSSM_DATA_PTR CipherBufs, 

uint32 CipherBufCount, 

uint32 *bytesEncrypted, 
CSSM_DATA_PTR RemData, 

CSSM_PRIVILEGE Privilege) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 
Privilege (input) 

The privilege to be applied during the cryptographic operation. 
See CSSM_EncryptData for other parameters. 


DESCRIPTION 


This function is similar to CSSM_EncryptData(). It also accepts a USEE tag as a privilege request parameter. 
CSSM checks that either its own privilege set or the application's privilege set (if the application is signed) 
includes the tag. | f the tag is found and the service provider privilege set indicates that it is supported, the tag 
is forwarded to the service provider. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CSP_BLOCK_SIZE_MISMATCH 
CSSMERR_CSP_OUTPUT_LENGTH_ERROR 
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SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 


Functions: CSSM_DecryptData, CSSM_EncryptDatal nit, CSSM_EncryptDataU pdate, 
CSSM _EncryptDataFinal, CSSM_EncryptDataP, CSSM_EncryptDatalnitP, CSSM_DecryptP, 
CSSM_DecryptDatal nitP, CSSM_QuerySize 
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EncryptDataU pdate 


NAME 


EncryptDataU pdate: CSSM_EncryptDataU pdate, CSP_EncryptDataU pdate - Continue the staged 
encryption process (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_EncryptDataUpdate 
(CSSM_CC_HANDLE CCHandle, 

const CSSM_DATA *ClearBufs, 

uint32 ClearBufCount, 

CSSM_DATA_PTR CipherBufs, 

uint32 CipherBufCount, 

uint32 *bytesEncrypted) 

SPL 
CSSM_RETURN CSSMCSPI CSP_EncryptDataUpdate 
(CSSM_CSP_HANDLE CSPHandle, 

CSSM_CC_HANDLE CCHandle, 

const CSSM_DATA *ClearBufs, 

uint32 ClearBufCount, 

CSSM_DATA_PTR CipherBufs, 

uint32 CipherBufCount, 

uint32 *bytesEncrypted) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


API PARAMETERS 


CCHandle (input) 


The handle that describes the context of this cryptographic operation used to link to the 
CSP-managed information. 


ClearBufs (input) 

A pointer toa vector of CSSM_DATA structures that contain the data to be operated on. 
ClearBufCount (input) 

The number of ClearBufs. 
CipherBufs (output) 


A pointer to a vector of CSSM_DATA structures that contain the encrypted data resulting 
from the encryption operation. 


CipherBufCount (input) 
The number of CipherBufs. 


bytesEncrypted (output) 
A pointer to uint32 for the size of the encrypted data in bytes. 


337 


SPI PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform calls to CSSM for the memory functions managed by CSSM. 


DESCRIPTION 


This function continues the staged encryption process over all data in the set of input buffers. There can be 
algorithm-specific and token-specific rules restricting the lengths of data in CSSM_EncryptUpdate () calls, but 
multiple input buffers are supported. The minimum number of buffers required to contain the resulting 
Gpher text is produced as output. Excess output buffer space is not remembered across staged encryption 
calls. Each staged call begins filling one or more new output buffers. The cSSM_QuerySize() function can be 
used to estimate the output buffer size required for each update call. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


None specific to this call. 


NOTES FOR API 


The output is returned to the caller either by filling the caller-specified buffer or by using the application's 
declared memory allocation functions to allocate buffer space. To specify a specific, preallocated output buffer, 
the caller must provide an array of oneor more CSSM_DATA structures, each containing a Length field value 
greater than zero and a non-NULL Data pointer field value. To specify automatic output buffer allocation by 
the CSP, the caller must provide an array of one or more CSSM_DATA structures, each containing a Length 
field value equal to zero and a NULL data pointer field value. The application is always responsible for 
deallocating the memory when it is no longer needed. | n-place encryption can be done by supplying the same 
input and output buffers. 


NOTES FOR SPI 


The output is returned to the caller as specified in Buffer Management for Cryptographic Services. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 
Functions for the CSSM API: 
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CSSM_QuerySize, CSSM_DecryptData, CSSM_EncryptDatal nit, CSSM_EncryptDataU pdate 
CSSM_EncryptDataFinal, CSSM_EncryptDataP, CSSM_EncryptDatalnitP, CSSM_DecryptP, 
CSSM_DecryptDatal nitP 


Functions for the CSP SPI: 
CSP_QuerySize CSP_DecryptData, CSP_EncryptDatal nit, CSP_EncryptDataF inal 
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FreeKey 
NAME 


Freek ey: CSSM_Freekey, CSP_Freek ey - Clean up keys (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 
CSSM_RETURN CSS 


(CSSM_CSP_HAND 


IAPI CSSM_FreeKey 


iF CSPHandle, 


const CSSM_ACCE 


SS_CREDENTIALS *AccessCred, 


CSSM_KEY_PTR Ke 
CSSM_BOOL Delet 
SPI: 
CSSM_RETURN CSS 


yPtr, 
e) 


MCSPI CSP_FreeKey 


(CSSM_CSP_HANDLI 


const CSSM_ACCE 


E CSPHandle, 
SS_CREDENTIALS *AccessCred, 


CSSM_KEY_PTR Ke 
CSSM_BOOL Delet 


LIBRARY 


yPtr, 
e) 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CSPHandle (input) 


The handle that describes the module to perform this operation. 


AccessCred (input/optional) 


KeyPtr (input) 


Delete (input) 
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If the target key referenced by KeyPtr is protected and Delete has the value CSSM_TRUE, 
this parameter must contain the certificates and samples required to access the target key. 
The certificates must be presented as immediate values in the input structure. The samples 
can be immediate values, be obtained through a protected mechanism, or be obtained 
through a callback function. 


The key whose associated keying material can be discarded at this time. 


If this value is CSSM_TRUE, the key data in the key structure will be removed and any 
internal storage related to that key will also be removed. In this case the key no longer 
exists in any form, unless previously wrapped out of the CSP by the application. If this 
value is CSSM_FALSE, then only the resources related to the key structure are released. 
The key may still be accessible by other means internally to the CSP. 


DESCRIPTION 


This function requests the Cryptographic Service Provider to clean up any key material associated with the 
key, and to possibly delete the key from the CSP completely. This function also releases the internal storage 
referenced by the K eyData field of the key structure, which can hold the actual key value. The key reference 
by KeyPtr can bea persistent key or a transient key. This function clears the cached copy of the key and can 
have an effect on the long term persistence or transience of the key. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


None specific to this call. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 
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GenerateAlgorithmParams 


NAME 


GenerateAlgorithmParams: CSSM_GenerateAlgorithmParams, CSP_GenerateAlgorithmParams - 
Generate algorithm parameters (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_GenerateAlgorithmParams 
(CSSM_CC_HANDLE CCHandle, 

uint32 ParamBits, 

CSSM_DATA PTR Param) 

SPI: 
CSSM_RETURN CSSMCSPI CSP_GenerateAlgorithmParams 
(CSSM_CSP_HANDLE CSPHandle, 

CSSM_CC_HANDLE CCHandle, 

const CSSM_CONTEXT *Context, 

uint32 ParamBits, 

CSSM_DATA_PTR Param, 

uint32 *NumberOfUpdatedAttributes, 
CSSM_CONTEXT_ATTRIBUTE_PTR *UpdatedAttributes) 


LIBRARY 


Common Security Services Manager library (cdsa$Sincssm300_shr.exe) 


API PARAMETERS 


CCHandle (input) 


The handle that describes the context of this cryptographic operation used to link to the 
CSP-managed information. 


ParamBits (input) 
Used to generate parameters for the algorithm (for example, Diffie-Hellman). 
Param (output) 


Pointer toa CSSM_DATA structure used to provide information to the parameter 
generation process, or to receive information resulting from the generation process that is 
not required as a parameter to the algorithm. For instance, phase 2 of the KEA algorithm 
requires a private random value, rA, and a public version, Ra, to be generated. The private 
value, rA, is added to the context and the public value, Ra, is returned to the caller. |n some 
cases, when both input and output is required, a data structure is passed to the algorithm. 
In this situation, Param->Data references the structure and Param->Length is set to the 
length of the structure. 


SPI PARAMETERS 


CSPHandle (input) 
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The handle that describes the add-in Cryptographic Service Provider module used to 
perform up calls to CSSM for the memory functions managed by CSSM. 


Context (input) 


Pointer to CSSM_ CONTEXT structure that describes the attributes with this context. 
Modifying this structure has no effect on the internal structure maintained by the CSSM. It 
is only a copy of the actual data. Changes to the context attributes must be returned using 
the UpdatedAttributes return parameter. 


NumberOfUpdatedAtt ributes (output) 


The number of CSSM_CONTEXT_ATTRIBUTE structures contained in the 
UpdatedAttributes array. If this valueis zero, UpdatedAttributes should be set to 
NULL. 


UpdatedAttributes (output) 


An array of attributes that will be added to the context should be returned using this 
parameter. Memory for the attribute structures should be allocated using the 
CSSM_UPCALLS callbacks provided to the service provider module when 
CSSM_SPI_ModuleAttach () is called. 


DESCRIPTION 


This function generates algorithm parameters for the specified context. These parameters include 
Diffie-Hellman key agreement parameters and DSA key generation parameters. In most cases the 
algorithm parameters will be added directly to the cryptographic context (by returning an array of 
CSSM_CONTEXT_ATTRIBUTE structures), but an algorithm may return some data to the caller via the 
Param parameter. The generated parameters are added to the context as an attribute of type 
CSSM_ATTRIBUTE_ALG PARAMS. Other attributes returned are added to the context, or replace existing 
values in the context. 


NOTES FOR API 


The output is returned to the caller either by filling the caller-specified buffer or by using the application's 
declared memory allocation functions to allocate buffer space. To specify a specific, pre-allocated output 
buffer, the caller must provide an array of one or more CSSM_DATA structures each, containing a Length 
field value greater than zero and anon-NULL data pointer field value. To specify automatic output buffer 
allocation by the CSP, the caller must provide an array of one or more CSSM_DATA structures, each 
containing a Length field value equal to zero and a NULL data pointer field value. The application is always 
responsible for deallocating the memory when it is no longer needed. 


NOTES FOR SPI 


The output is returned to the caller as specified in Buffer Management for Cryptographic Services. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 
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None specific to this call. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 
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GenerateK ey 


NAME 
GenerateK ey: CSSM_GenerateK ey, CSP_GenerateK ey - Generate a symmetric key (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 
CSSM_RETURN CSSMAPI CSSM_GenerateKey 

(CSSM_CC_HANDLE CCHandle, 

uint32 KeyUsage, 

uint32 KeyAttr, 

const CSSM_DATA *KeyLabel, 

const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry, 
CSSM_KEY_PTR Key) 
SPI: 
CSSM_RETURN CSSMCSPI CSP_GenerateKey 

(CSSM_CSP_HANDLE CSPHandle, 

CSSM_CC_HANDLE CCHandle, 

const CSSM_CONTEXT *Context, 

uint32 KeyUsage, 

uint32 KeyAttr, 

const CSSM_DATA *KeyLabel, 

const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry, 
CSSM_KEY_PTR Key) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


API PARAMETERS 


CCHandle (input) 


The handle that describes the context of this cryptographic operation used to link to the 
CSP-managed information. 


KeyUsage (input) 

A bit mask indicating all permitted uses for the new key. 
KeyAttr (input) 

A bit mask defining attribute values for the new key. 
KeyLabel (input/optional) 

Pointer to a byte string that will be used as the label for the key. 
CredAndAclEntry (input/optional) 


A structure containing one or more credentials authorized for creating a key and the 
prototype ACL entry that will control future use of the newly created key. The credentials 
and ACL entry prototype can be presented as immediate values or callback functions can be 
provided for use by the CSP to acquire the credentials and/or the ACL entry interactively. | f 
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the CSP provides public access for creating a key, then the credentials can be NULL. If the 
CSP defines a default initial ACL entry for the new key, then the ACL entry prototype can 
be an empty list. 

Key (output) 


Pointer to CSSM_KEY structure used to hold the new key. The CSSM_KEY structure 
should be empty upon input to this function. The CSP will ignore any values residing in this 
structure at function invocation. Input values should be supplied in the cryptographic 
context, KeyUsage, KeyAttr, and KeyLabel input parameters. 


SPI PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform up-calls to CSSM for the memory functions managed by CSSM. 


Context (input) 
Pointer to CSSM_ CONTEXT structure that describes the attributes with this context. 
Key (output) 


Pointer to CSSM_KEY structure used to obtain the key. Upon function invocation, any 
values inthe CSSM_Key structure should be ignored. All input values should be supplied in 
the cryptographic Context, KeyUsage, KeyAttr, and KeyLabel input parameters. 


DESCRIPTION 


This function generates a symmetric key. The KeyUsage, and KeyAttr are used to initialize the keyheader for 
the newly created key. These values are not retained in the cryptographic Context, which contains additional 
parameters for this operation. The CSP may cache keying material associated with the new symmetric key. 
When the symmetric key is no longer in active use, the application can invoke the CSSM_FreeKey () interface 
to allow cached keying material associated with the symmetric key to be removed. 


Authorization policy can restrict the set of callers who can create a new resource. In this case, the caller must 
present a set of access credentials for authorization. Upon successfully authenticating the credentials, the 
template that verified the presented samples identifies the ACL entry that will be used in the authorization 
computation. If the caller is authorized, the new resource is created. 


The caller must provide an initial ACL entry to be associated with the newly created resource. This entry is 
used to control future access to the new resource and (since the subject is deemed to be the "Owner") exercise 
control over its associated ACL. The caller can specify the following items for initializing an ACL entry: 


e Subject -A CSSM_LIST structure, containing the type of the subject and a template value that can be 
used to verify samples that are presented in credentials when resource access is requested. 


¢« Delegation flag - A value indicating whether the Subject can delegate the permissions recorded in the 
AuthorizationTag. (This item only applies to public key subjects). 


e Authorization tag - The set of permissions that are granted to the Subject. 
e Validity period - The start time and the stop time for which the ACL entry is valid. 
¢ ACL entry tag - A user-defined string value associated with the ACL entry. 


The service provider can modify the caller-provided initial ACL entry to conform to any innate 
resource-access policy that the service provider may be required to enforce. If the initial ACL entry 
provided by the caller contains values or permissions that are not supported by the service provider, then 
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the service provider can modify the initial ACL appropriately or can fail the request to create the new 
resource. Service providers list their supported AuthorizationTag values in their Module Directory 
Services primary record. 


NOTES 


The KeyData field of the CSSM_KEY structureis allocated by the CSP. The application is required to free this 
memory using the CSSM_FreeKey () (CSSM API), or CSP_FreeKey () (CSP SPI), function or with the memory 
functions registered for the cSPHandle. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CSP_KEY_LABEL_ALREADY_EXISTS 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 
CSSM_GenerateRandom, CSSM_GenerateK eyPair 
Functions for the CSP SPI: 
CSP_GeerateRandom, CSP_GenerateKeyPair 
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GenerateK eyP 
NAME 
GenerateK eyP - Generate a key with privilege (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_GenerateKeyP 

(CSSM_CC_HANDLE CCHandle, 

uint32 KeyUsage, 

uint32 KeyAttr, 

const CSSM_DATA *KeyLabel, 

const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry, 
CSSM_KEY_PTR Key, 

CSSM_PRIVILEGE Privilege) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


Privilege (input) 
The privilege to be applied during the cryptographic operation. 
See CSSM_GeerateKey for other parameters. 


DESCRIPTION 


This function is similar to the cSSM_GenerateKey () function. It also accepts a USEE tag as a privilege 
request parameter. CSSM checks that either its own privilege set or the application's privilege set (if the 
application is signed) includes the tag. If the tag is found and the service provider privilege set indicates that 
it is supported, the tag is forwarded to the service provider. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 
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Online Help 
Functions: CSSM_Generat&KeyPairP, CSSM_GeneratRRandom 
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GenerateK eyPair 
NAME 


GenerateK eyPair: CSSM_GenerateK eyPair, CSP_GenerateK eyPair - Generate an asymmetric key 
pair (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_GenerateKeyPair 
(CSSM_CC_HANDLE CCHandle, 

uint32 PublicKeyUsage, 

uint32 PublicKkeyAttr, 

const CSSM_DATA *PublicKeyLabel, 
CSSM_KEY_PTR PublicKey, 

uint32 PrivateKeyUsage, 

uint32 PrivateKeyAttr, 

const CSSM_DATA *PrivateKeyLabel, 


const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry, 
CSSM_KEY_PTR PrivateKey) 

SPIs 
CSSM_RETURN CSSMCSPI CSP_GenerateKeyPair 
(CSSM_CSP_HANDLE CSPHandle, 

CSSM_CC_HANDLE CCHandle, 

const CSSM_CONTEXT *Context, 

uint32 PublicKeyUsage, 

uint32 PublicKkeyAttr, 

const CSSM_DATA *PublicKeyLabel, 

CSSM_KEY_PTR PublickKey, 

uint32 PrivateKeyUsage, 

uint32 PrivateKeyAttr 

const CSSM_DATA *PrivateKeyLabel, 

const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry, 
CSSM_KEY_PTR PrivateKey, 

CSSM_PRIVILEGE Privilege) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


API PARAMETERS 


CCHandle (input) 


The handle that describes the context of this cryptographic operation used to link to the 
CSP-managed information. 


PublicKeyUsage (input) 
A bit mask indicating all permitted uses for the new public Key. 
PublicKeyAttr (input) 


A bit mask defining attribute values for the new public key. 


PublicKeyLabel (input/optional) 
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Pointer to a byte string that will be used as the label for the public key. 
PublicKkey (output) 


Pointer toCSSM_KEY structure used to hold the new public key. The CSSM_KEY structure 
should be empty upon input to this function. The CSP will ignore any values residing in this 
structure at function invocation. Input values should be supplied in the cryptographic 
Context, PublicKeyUsage, PublicKeyAttr, and PublicKeyLabel input parameters. 


PrivateKeyUsage (input) 
A bit mask indicating all permitted uses for the new private key. 
PrivateKeyAttr (input) 


A bit mask defining attribute values for the new private key. 


PrivateKeyLabel (input/optional) 
Pointer to a byte string that will be used as the label for the private key. 


CredAndAclEntry (input/optional) 


A structure containing one or more credentials authorized for creating a key and the 
prototype ACL entry that will control future use of the newly created key. The credentials 
and ACL entry prototype can be presented as immediate values or callback functions can be 
provided for use by the CSP to acquire the credentials and/or the ACL entry interactively. | f 
the CSP provides public access for creating a key, then the credentials can be NULL. If the 
CSP defines a default initial ACL entry for the new key, then the ACL entry prototype can 
be an empty list. 


PrivateKey (output) 


Pointer to CSSM_KEY structure used to obtain the private key. Upon function invocation, 
any values in the CSSM_Key structure should be ignored. All input values should be 
supplied in the cryptographic context, PrivateKeyUsage, PrivateKeyAttr, and 
PrivateKeyLabel input parameters. 


SPI PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform calls to CSSM for the memory functions managed by CSSM. 


CCHandle (input) 


The handle that describes the context of this cryptographic operation used to link to the 
CSP-managed information. 


Context (input) 
Pointer to CSSM_ CONTEXT structure that describes the attributes with this context. 
Privilege (input) 


The export privilege to be applied during the cryptographic operation. This parameter is 
forwarded to the CSP after CSSM verifies the caller and service provider privilege set 
includes the specified privilege. 
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DESCRIPTION 


This function generates an asymmetric key pair. The CSP may cache keying material associated with the new 
asymmetric keypair. When one or both of the keys are no longer in active use, the application can invoke the 
CSSM_FreeKey () interface to allow cached keying material associated with the key to be removed. 


Authorization policy can restrict the set of callers who can create a new resource. In this case, the caller must 
present a set of access credentials for authorization. Upon successfully authenticating the credentials, the 
template that verified the presented samples identifies the ACL entry that will be used in the authorization 
computation. If the caller is authorized, the new resource is created. 


The caller must provide an initial ACL entry to be associated with the newly created resource. This entry is 
used to control future access to the new resource and (since the subject is deemed to be the "Owner") exercise 
control over its associated ACL. The caller can specify the following items for initializing an ACL entry: 


e« Subject -A CSSM_LIST structure, containing the type of the subject and a template value that can be 
used to verify samples that are presented in credentials when resource access is requested. 


¢« Delegation flag - A value indicating whether the Subject can delegate the permissions recorded in the 
AuthorizationTag. (This item only applies to public key subjects). 


e« Authorization tag - The set of permissions that are granted to the Subject. 
e Validity period - The start time and the stop time for which the ACL entry is valid. 
¢ ACL entry tag - A user-defined string value associated with the ACL entry. 


The service provider can modify the caller-provided initial ACL entry to conform to any innate 
resource-access policy that the service provider may be required to enforce. If the initial ACL entry 
provided by the caller contains values or permissions that are not supported by the service provider, then 
the service provider can modify the initial ACL appropriately or can fail the request to create the new 
resource. Service providers list their supported AuthorizationTag values in their Module Directory 
Services primary record. 


NOTES 


The KeyData fields of the CSSM_KEY structures are allocated by the CSP. The application is required to free 
this memory using the cSSM_FreeKey () (CSSM API), or CSP_FreeKey () (CSP SPI), function or with the 
memory functions registered for the cSPHandle. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CSP_KEY_LABEL_ALREADY_EXISTS 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


352 


Online Help 

Functions for the CSSM API: 
CSSM_GenerateKey, CSSM_GemeratRandom 
Functions for the CSP SPI: 

CSP_GeerateKey, CSP_GeerateRandom 
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GenerateK eyPairP 
NAME 


GenerateK eyPairP - Generate an asymmetric key pair with privilege (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_GenerateKeyPairP 
(CSSM_CC_HANDLE CCHandle, 

uint32 PublicKeyUsage, 

uint32 PublicKkeyAttr, 

const CSSM_DATA *PublicKeyLabel, 
CSSM_KEY_PTR PublicKey, 

uint32 PrivateKeyUsage, 

uint32 PrivateKeyAttr, 

const CSSM_DATA *PrivateKeyLabel, 

const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry, 
CSSM_KEY_PTR PrivateKey, 

CSSM_PRIVILEGE Privilege) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 
Privilege (input) 

The privilege to be applied during the cryptographic operation. 
See CSSM_Geerat&KeyPair. 


DESCRIPTION 


This function is similar to the cSSM_GenerateKeyPair() function. It also accepts a USEE tag as a privilege 
request parameter. CSSM checks that either its own privilege set or the application's privilege set (if the 
application is signed) includes the tag. If the tag is found and the service provider privilege set indicates that 
it is supported, the tag is forwarded to the service provider. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CSP_KEY_LABEL_ALREADY_EXISTS 
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SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 
Functions: CSSM_ Generate eyPair 
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GenerateMac 
NAME 


GenerateM ac: CSSM_GenerateMac, CSP_GenerateM ac - Compute a message authentication code 
(CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_GenerateMac 
(CSSM_CC_HANDLE CCHandle, 

const CSSM_DATA *DataBufs, 

uint32 DataBufCount, 

CSSM_DATA_PTR Mac) 

SPI: 
CSSM_RETURN CSSMCSPI CSP_GenerateMac 
(CSSM_CSP_HANDLE CSPHandle, 
CSSM_CC_HANDLE CCHandle, 

const CSSM_CONTEXT *Context, 

const CSSM_DATA *DataBufs, 

uint32 DataBufCount, 

CSSM_DATA_PTR Mac) 


LIBRARY 


Common Security Services Manager library (cdsa$Sincssm300_shr.exe) 


API PARAMETERS 


CCHandle (input) 


The handle that describes the context of this cryptographic operation used to link to the 
CSP-managed information. 


Dat aBufs (input) 
A pointer toa vector of CSSM_DATA structures that contain the data to be operated on. 
Dat aBufCount (input) 


The number of DataBufs. 


Mac (output) 
A pointer tothe CSSM_DATA structure for the Message Authentication Code. 


SPI PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform calls to CSSM for the memory functions managed by CSSM. 


Context (input) 
Pointer to CSSM_CONTEXT structure that describes the attributes with this context. 
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DESCRIPTION 


This function computes a message authentication code for all data contained in the set of input buffers. 


NOTES ON API 


The output is returned to the caller either by filling the caller-specified buffer or by using the application's 
declared memory allocation functions to allocate buffer space. To specify a specific, preallocated output buffer, 
the caller must provide an array of one or more CSSM_DATA structures, each containing a Length field value 
greater than zero and a non-NULL data pointer field value. To specify automatic output buffer allocation by 
the CSP, the caller must provide an array of one or more CSSM_DATA structures, each containing a Length 
field value equal to zero and a NULL data pointer field value. The application is always responsible for 
deallocating the memory when it is no longer needed. 


NOTES ON SPI 


The output is returned to the caller as specified in Buffer Management for Cryptographic Services. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CSP_OUTPUT_LENGTH_ERROR 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 

CSSM_GenerateMaci nit, CSSM_GemerateMacU pdate, CSSM_GenerateMacF inal 
Functions for the CSP SPI: 

CSP_GeerateMacl nit, CSP_GenerateM acU pdate CSP_GeerateM acF inal 
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GenerateMacF inal 
NAME 


GenerateM acFinal: CSSM_GenerateMacFinal, CSP_GenerateM acF inal - Finalize the staged 
message authentication code (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_GenerateMacFinal 
(CSSM_CC_HANDLE CCHandle, 

CSSM_DATA_PTR Mac) 

SPI: 
CSSM_RETURN CSSMCSPI CSP_GenerateMacFinal 
(CSSM_CSP_HANDLE CSPHandle, 
CSSM_CC_HANDLE CCHandle, 

CSSM_DATA_PTR Mac) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


API PARAMETERS 


CCHandle (input) 


The handle that describes the context of this cryptographic operation used to link to the 
CSP-managed information. 


Mac (output) 
A pointer tothe CSSM_DATA structure for the message authentication code. 


SPI PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform calls to CSSM for the memory functions managed by CSSM. 


DESCRIPTION 


This function finalizes the staged message authentication code function. 


NOTES ON API 


The output is returned to the caller either by filling the caller-specified buffer or by using the application's 
declared memory allocation functions to allocate buffer space. To specify a specific, preallocated output buffer, 
the caller must provide an array of oneor more CSSM_DATA structures, each containing a Length field value 
greater than zero and a non-NULL data pointer field value. To specify automatic output buffer allocation by 
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the CSP, the caller must provide an array of one or more CSSM_DATA structures, each containing a Length 
field value equal to zero and a NULL data pointer field value. The application is always responsible for 
deallocating the memory when it is no longer needed. 


NOTES ON SPI 


The output is returned to the caller as specified in Buffer Management for Cryptographic Services. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CSP_OUTPUT_LENGTH_ERROR 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 

CSSM_GenerateMac, CSSM_GenerateMacli nit, CSSM_GenerateMacU pdate 
Functions for the CSP SPI: 

CSP_GmerateM ac, CSP_GenerateM acl nit, CSP_GenerateM acU pdate 


359 


GenerateMacli nit 
NAME 


GenerateM acl nit: CSSM_GenerateM acl nit, CSP_GenerateM acl nit - Initialize the staged message 
authentication code (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_GenerateMacInit 
(CSSM_CC_HANDLE CCHandle) 

SPI: 
CSSM_RETURN CSSMCSPI CSP_GenerateMacInit 
(CSSM_CSP_HANDLE CSPHandle, 
CSSM_CC_HANDLE CCHandle, 

const CSSM_CONTEXT *Context) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


API PARAMETERS 


CCHandle (input) 


The handle that describes the context of this cryptographic operation used to link to the 
CSP-managed information. 


SPI PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform calls to CSSM for the memory functions managed by CSSM. 


Context (input) 
Pointer to CSSM_CONTEXT structure that describes the attributes with this context. 


DESCRIPTION 


This function initializes the staged message authentication code function. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 


Errors are described in the CDSA Technical Standard. 
None specific to this call. 
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SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 

CSSM_GenerateMac, CSSM_GenerateMacU pdate, CSSM_GeerateMacFinal 
Functions for the CSP SPI: 

CSP_GmerateM ac, CSP_GenerateM acU pdate, CSP_GenerateM acF inal 
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GenerateMacU pdate 


NAME 


GenerateM acU pdate: CSSM_GenerateM acU pdate, CSP_GenerateMacU pdate - Continue the 
staged process of computing a message authentication code (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_GenerateMacUpdate 
(CSSM_CC_HANDLE CCHandle, 

const CSSM_DATA *DataBufs, 

uint32 DataBufCount) 

SPI: 
CSSM_RETURN CSSMCSPI CSP_GenerateMacUpdate 
(CSSM_CSP_HANDLE CSPHandle, 

CSSM_CC_HANDLE CCHandle, 

const CSSM_DATA *DataBufs, 

uint32 DataBufCount) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


API PARAMETERS 


CCHandle (input) 


The handle that describes the context of this cryptographic operation used to link to the 
CSP-managed information. 


DataBufs (input) 
A pointer toa vector of CSSM_DATA structures that contain the data to be operated on. 
Dat aBufCount (input) 


The number of DataBufs. 


SPI PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform calls to CSSM for the memory functions managed by CSSM. 


DESCRIPTION 


This function continues the staged process of computing a message authentication code over all data 
contained in the set of input buffers. The authentication code will be returned as a result of the final code 
generation step. 
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RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 


indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


None specific to this call. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 

CSSM_GenerateMac, CSSM_GenerateMacli nit, CSSM_GenerateMacF inal 
Functions for the CSP SPI: 

CSP_GmerateMac, CSP_GenerateM acl nit, CSP_GenerateM acF inal 
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GenerateRandom 
NAME 


GenerateRandom: CSSM_GenerateRandom, CSP_GenerateRandom function - Generate random 
data (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_GenerateRandom 
(CSSM_CC_HANDLE CCHandle, 

CSSM_DATA_PTR RandomNumber) 

SPI: 
CSSM_RETURN CSSMCSPI CSP_GenerateRandom 
(CSSM_CSP_HANDLE CSPHandle, 
CSSM_CC_HANDLE CCHandle, 

const CSSM_CONTEXT *Context, 
CSSM_DATA_PTR RandomNumber) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


API PARAMETERS 


CCHandle (input) 


The handle that describes the context of this cryptographic operation used to link to the 
CSP-managed information. 


RandomNumber (output) 


Pointer to CSSM_DATA structure used to obtain the random number and the size of the 
random number in bytes. 


SPI PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform calls to CSSM for the memory functions managed by CSSM. 


Context (input) 
Pointer to CSSM_ CONTEXT structure that describes the attributes with this context. 


DESCRIPTION 


This function generates random data. 
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NOTES ON API 


The output is returned to the caller either by filling the caller-specified buffer or by using the application's 
declared memory allocation functions to allocate buffer space. To specify a specific, preallocated output buffer, 
the caller must provide an array of one or more CSSM_DATA structures, each containing a Length field value 
greater than zero and a non-NULL data pointer field value. To specify automatic output buffer allocation by 
the CSP, the caller must provide an array of one or more CSSM_DATA structures, each containing a Length 
field value equal to zero and a NULL data pointer field value. The application is always responsible for 
deallocating the memory when it is no longer needed. 


NOTES ON SPI 


The output is returned to the caller as specified in Buffer Management for Cryptographic Services. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 


Errors are described in the CDSA Technical Standard. 
None specific to this call. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 
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GetOperational Statistics 


NAME 


GetOperational Statistics: CSSM_CSP_GetOperationalStatistics, CSP_GetOperationalStatistics - 
Get operational values of a subservice (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_CSP_GetOperationalStatistics 
(CSSM_CSP_HANDLE CSPHandle, 

CSSM_CSP_OPERATIONAL_ STATISTICS *Statistics) 

SP Es 
CSSM_RETURN CSSMCSPI CSSM_CSP_GetOperationalStatistics 
(CSSM_CSP_HANDLE CSPHandle, 

CSSM_CSP_OPERATIONAL_ STATISTICS *Statistics) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 
CSPHandle (input) 

Handle of the Cryptographic Service Provider that will perform the operation. 
Statistics (output) 

Structure containing the subservice's current statistics. 


DESCRIPTION 


Obtain the current operational values of a subservice. The information is returned in a structure of type 
CSSM_CSP_OPERATIONAL_STATISTICS. This information includes login status and available storage 
space. The data structure to hold the returned results must be provided by the caller. The CSP does not 
allocate memory on behalf of the caller. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


None specific to this call. 
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SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 
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GetTimeValue 


NAME 
GetTimeValue: CSSM_GetTimeValue, CSP_GetTimeValue - Get a CSP time value (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_GetTimeValue 
(CSSM_CSP_HANDLE CSPHandle, 
CSSM_ALGORITHMS TimeAlgorithm, 
CSSM_DATA *TimeData) 

SPI: 
CSSM_RETURN CSSMCSPI CSP_GetTimeValue 
(CSSM_CSP_HANDLE CSPHandle, 
CSSM_ALGORITHMS TimeAlgorithm, 
kCSSM_DATA *TimeData) 


LIBRARY 


Common Security Services Manager library (cdsa$Sincssm300_shr.exe) 


PARAMETERS 


CSPHandle (input) 
Handle of the Cryptographic Service Provider that will perform the operation. 


TimeAlgorithm (input) 


A CSSM algorithm type that indicates the method for fetching the time. The following 
algorithm types are supported: 


CSSM_ALGID_UTC Returns a time value in the form YY YYMMDDhhmmss (4 characters 
for the year; 2 characters each for the month, the day, the hour, the minute, and the second). 
The time returned is GMT. 


CSSM_ALGID_ RUNNING COUNTER Thecurrent value of a running hardware counter 
that operates while the device is in operation. This value can be read from a processor 
counter provided by some platform architectures. 


TimeData (output) 


The time value of counter value returned in response to the request. 


DESCRIPTION 


This function returns a time value maintained by a CSP. This feature will be supported primarily by 
hardware tokens with an onboard real time clock. 
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NOTES 


The output is returned to the caller either by filling the caller-specified buffer or by using the application's 
declared memory allocation functions to allocate buffer space. To specify a specific, preallocated output buffer, 
the caller must provide an array of one or more CSSM_DATA structures, each containing a Length field value 
greater than zero and a non-NULL data pointer field value. To specify automatic output buffer allocation by 
the CSP, the caller must provide an array of one or more CSSM_DATA structures, each containing a Length 
field value equal to zero and a NULL data pointer field value. The application is always responsible for 
deallocating the memory when it is no longer needed. 


Some tokens require authentication before returning a time value. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 


Errors are described in the CDSA Technical Standard. 
None specific to this call. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 
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MDS Initialize 
NAME 
MDS_Initialize - Initiate service context with MDS (CDSA) 


SYNOPSIS 


#include <cdsa/mds.h> 


CSSM_RETURN CSSMAPI MDS_Initialize 

(const CSSM_GUID *pCallerGuid, 

const CSSM_DATA *pCallerManifest, 

const CSSM_MEMORY_FUNCS *pMemoryFunctions, 
MDS_FUNCS_PTR pDlFunctions, 

MDS_HANDLE *hMds) 


LIBRARY 


Module Directory Services library (cdsa$mds300_shr.exe) 


PARAMETERS 
pCallerGuid (input/optional) 
The GUID of the module calling MDS. 
pCallerManifest (input/optional) 
The Manifest of the module calling MDS. 


pMemoryFunctions (input) 


The memory-management routines MDS uses to allocate query results on behalf of the 
caller. 


pD1Functions (output) 
The function table containing MDS programming interfaces for database access. 
hMds (output) 


A new handle that can be used to interact with the MDS. The value will be set to 
CSSM_INVALID_HANDLE if the function fails. 


DESCRIPTION 


This function initiates a service context with MDS and returns an opaque handle corresponding to that 


context. The caller provides memory functions that MDS can use to manage memory in the caller's space on 
behalf of the caller. The caller also provides input/output table pDIF unctions to get access to MDS databases. 


If the caller is a CDSA service provider that will require write-access to an MDS database, (Such as a module 
that supports dynamic insertion and removal events), then the caller can provide the caller's GUID as input 
parameter pCallerGuid. When provided as input, the GUID is associated with the MDS handle and is used 


during DbOpen processing. If write-access is requested during DbOpen, MDS uses the associated GUID to 
locate the service provider's signed manifest credentials in the DS Common relation. The service provider 
module and its credentials are verified to ensure that write-access is permitted on this database by this 
module. 
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The installers will have to provide the pcallerManifest instead of pcallerGuid, as GUID cannot be used to 
locate an application unless it is installed. Only one of the two parameters pcallerGuid and 
pCallerManifest should benon NULL in an MDS_Initialize() call, otherwise an error will be returned. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


Errors are described in the CDSA Technical Standard. 
CSSMERR_DL_ INVALID POINTER 

CSSMERR_DL_INTERNAL ERROR 
CSSMERR_DL_MEMORY_ERROR 

CSSMERR_DL_ FUNCTION _FATLED 

Books 


Inta CDSA Application Devdoper's Guide 
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MDS Install 


NAME 
MDS _ Install - Create the object directory database (CDSA) 


SYNOPSIS 


#include <cdsa/mds.h> 


CSSM_RETURN CSSMAPI MDS_Install 
(MDS_HANDLE MdsHandle) 


LIBRARY 


Module Directory Services library (cdsa$mds300_shr.exe) 


PARAMETERS 


MdsHandle (input) 
The MDS handle identifying an MDS context. 


DESCRIPTION 


This function creates the Object Directory database containing the object relation, and the CDSA Directory 
database containing the set of CDSA-specific relations defined in this specification. The MdsHandle identifies 
an MDS context created by invoking MDS_Initialize(). The context contains information about the access 
rights of the caller. Write-access is required to perform this operation. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 

Errors are described in the CDSA Technical Standard. 
CSSMERR_DL_INVALID_DL_HANDLE 
CSSMERR_DL_DATASTORE_ALREADY_EXISTS 
CSSMERR_DL_INVALID_ACCESS_REQUEST 
CSSMERR_DL_INVALID_DB LOCATION 
CSSMERR_DL_ INVALID _DB_ NAME 
CSSMERR_DL_INVALID_OPEN PARAMETERS 
CSSMERR_DL_INVALID_RECORD_INDEX 
CSSMERR_DL_INVALTID_RECORDTYPE 
CSSMERR_DL_INVALID_ FIELD NAMF 
CSSMERR_DL_ UNSUPPORTED FIELD FORMA 
CSSMERR_DL_UNSUPPORTED_INDEX_INFO 
CSSMERR_DL_UNSUPPORTED_LOCALITY 
CSSMERR_DL_UNSUPPORTED_NUM_ATTRIBUTES 
CSSMERR_DL_UNSUPPORTED_NUM_INDEXES 
CSSMERR_DL_ UNSUPPORTED _NUM_RECORDTYPES 
CSSMERR_DL_UNSUPPORTED_RECORDTYPE 
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CSSMERR_DL_FIELD_SPECIFIED_MULTIPLE 
CSSMERR_DL_INCOMPATIBLE_FIELD_FORMAT 
CSSMERR_DL_INVALID_PARSING_MODULE 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 
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MDS Terminate 


NAME 
MDS_Terminate - Terminate the MDS service context (CDSA) 


SYNOPSIS 


#include <cdsa/mds.h> 


CSSM_RETURN CSSMAPI MDS_Terminate 
(MDS_HANDLE MdsHandle) 


LIBRARY 


Module Directory Services library (cdsa$mds300_shr.exe) 


PARAMETERS 


MdsHandle (input) 


The MDS handle corresponding to the context being terminated. 


DESCRIPTION 


This function terminates the MDS service context identified by the opaque MdsHandle. The MDS handle is 
invalidated and MDS frees all internal resources associated with the context. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_DL_INVALID_DL_HANDLE 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 
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MDS _ Uninstall 


NAME 
MDS_Uninstall - Delete the object directory database (CDSA) 


SYNOPSIS 


#include <cdsa/mds.h> 


CSSM_RETURN CSSMAPI MDS_Uninstall 
(MDS_HANDLE MdsHandle) 


LIBRARY 


Module Directory Services library (cdsa$mds300_shr.exe) 


PARAMETERS 
MdsHandle (input) 
The MDS handle identifying a valid MDS context. 


DESCRIPTION 


This function deletes the Object Directory database containing the object relation, and the CDSA Directory 
database containing the set of CDSA-specific relations defined in this specification. The MdsHandle identifies 
the MDS context created by invoking MDS_Initialize(). The context contains information about the access 
rights of the caller. Write-access is required to perform this operation. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_DL_INVALID_DL_HANDLE CSSMERR_DL_DATASTORE_IS_OPEN 
CSSMERR_DL_INVALID_DB_LOCATION CSSMERR_DL_INVALID_DB_NAME 
CSSMERR_DL_DATASTORE_DOESNOT_EXIST 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 
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MDSUTIL_FreeModulel nfo 


NAME 
MDSUTIL_FreeM odulel nfo - Frees memory associated with the MDSUTIL_GetM odulel nfo 
function. 


SYNOPSIS 
#include <mds_util_api.h> 
#include <mds_util_helper.h> 


CSSM_RETURN CSSMAPI MDSUTIL_FreeModuleInfo 
(MDSUTIL_MODULE_INFO_PTR ModuleInfo) 


LIBRARY 


Module Directory Services library (cdsa$mds300_shr.exe) 


PARAMETERS 


ModuleInfo (input) 
A pointer to the data to be freed. 


DESCRIPTION 


This routine frees the list of module information that was returned by MDSUTIL_GetM odulel nfo. All 
substructures within the info structure are freed by this function. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition.The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 


Errors are described in the CDSA Technical Standard. 


CSSMERR_CSSM_INVALID_POINTER 
CSSMERR_CSSM_NOT_INITIALIZED 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 


Functions: MDSUTIL_Moduleinstall, MDSUTIL_ModuleUninstall, MDSUTIL_ListModules, 
MDSUTIL_Ge&Moduld nfo, MDSUTIL_Ge&CredLocationFromGUID, MDSUTIL_FreeM odulet ist, 
MDSUTIL_ListModuleM anagers, MDSUTIL_GetM oduleM anager! nfo, MDSUTIL_ModuleM anage|nstall, 
MDSUTIL_ModuleManagerUninstall, MDSUTIL_Init, MDSUTIL_Taem 
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MDSUTIL_FreeModuleList 


NAME 
MDSUTIL_FreeM oduleList - Frees the list of add-in modules that was returned by 
MDSUTIL_ListM odules. 


SYNOPSIS 
#include <mds_util_api.h> 
#include <mds_util_helper.h> 


CSSM_RETURN CSSMAPI MDSUTIL_FreeModuleList 
(MDSUTIL_LIST_PTR List) 


LIBRARY 


Module Directory Services library (cdsa$mds300_shr.exe) 


PARAMETERS 
List (input) 
A pointer toa MDSUTIL_LIST pointer. 


DESCRIPTION 
This routine frees the list of add-in modules that was returned by MDSUTIL_ListM odules. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition.The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 


Errors are described in the CDSA Technical Standard. 
CSSMERR_CSSM_INVALID_POINTER 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 


Functions: MDSUTIL_Moduleinstall, MDSUTIL_ModuleUninstall, MDSUTIL_ListModules, 
MDSUTIL_Ge&Moduld nfo, MDSUTIL_Ge&CredLocationFromGUID, MDSUTIL_FreeModuld nfo, 
MDSUTIL_ListModuleM anagers, MDSUTIL_GetM oduleM anager nfo, MDSUTIL_ModuleManagetnstall, 
MDSUTIL_ModuleManagerUninstall, MDSUTIL_Init, MDSUTIL_Tem 
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MDSUTIL_GetCredLocationF romGUID 


NAME 


MDSUTIL_GetCredLocationFromGUID - Returns the location of the add-in module, and the 
associated credentials file for the add-in module. 


SYNOPSIS 


#include <mds_util_api.h> 
#include <mds_util_helper.h> 


CSSM_RETURN CSSMAPI MDSUTIL_GetCredLocationFromGUID 
(const CSSM_GUID *ModuleGUID, 

CSSM_DATA *pModulePath, 

CSSM_DATA *pModuleCredentialPath, 
CSSM_API_MEMORY_FUNCS_PTR MemoryFuncs) 


LIBRARY 


Module Directory Services library (cdsa$mds300_shr.exe) 


PARAMETERS 


ModuleGUID (input) 
A pointer to the module's Globally Unique ID. 
pModulePath (output) 


A pointer to the module's full filespec location. 


pModuleCredentialPath (output) 
A pointer to the module's credential full filespec location. 
MemoryFuncs (input) 


The memory-management routines MDS uses to allocate query results on behalf of the 
caller. 


DESCRIPTION 


This function returns the location of the add-in module, and the associated credentials file for the add-in 
module. The caller is responsible for freeing the memory in the output parameters. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 


Errors are described in the CDSA Technical Standard. 


CSSMERR_CSSM_INVALID_GUID 
CSSMERR_CSSM_MDS ERROR 
CSSM_ERRCODE_INVALID_OUTPUT_ POINTER 
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CSSM_ERRCODE_MEMORY_ERROR 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 


Functions: MDSUTIL_Moduleinstall, MDSUTIL_ModuleUninstall, MDSUTIL_ListModules, 
MDSUTIL_Ge&Moduld nfo, MDSUTIL_FreeM oduld nfo, MDSUTIL_FreeModuleList, 
MDSUTIL_ListModuleV anagers, MDSUTIL_GetModuleManagerI nfo, MDSUTIL_ModuleManageI nstall, 
MDSUTIL_ModuleManageUninstall, MDSUTIL_Init, MDSUTIL_Taem 


379 


MDSUTIL_GetModulel nfo 


NAME 
MDSUTIL_GetM odulel nfo - Gets information from the MDS registry for the add-in module. 


SYNOPSIS 


#include <mds_util_api.h> 
#include <mds_util_helper.h> 


CSSM_RETURN CSSMAPI MDSUTIL_GetModuleInfo 
(const CSSM_GUID *ModuleGUID, 
CSSM_SERVICE_MASK UsageMask, 

uint32 SubservicelID, 

CSSM_USEE_TAG USEERequest, 
MDSUTIL_MODULE_INFO_PTR *pModuleInfo) 


LIBRARY 


Module Directory Services library (cdsa$mds300_shr.exe) 


PARAMETERS 


ModuleGUID (input) 


A pointer tothe CSSM_GUID structure containing the Globally Unique ID of the add-in 
module. 


UsageMask (input) 


A bit mask specifying the module usage types used to restrict the capabilities information 
returned by this function. An input value of zero specifies all usages for the specified 
module. 


SubservicelID (input) 


A single subservice |D. Note that the operation may already be limited by a service mask. If 
so, the subservice|D applies to all service categories selected by the service mask. 


USEERequest (input) 
United States Export Exemption tag; should be set to CSSM_USEE NONE. 


pModuleInfo (output) 
A pointer to the module information. 


DESCRIPTION 


This function gets a list of descriptive information from the MDS registry for the add-in module identified by 
the ModuleGUID. The information returned can include all of the capability information for each of the 
subservices for each of the service types implemented by the selected module. The request for information can 
be limited to a particular set of services, as specified by the UsageM ask. The request may be further limited to 
one or all of the subservices implemented in one or all of the service categories. The 

MDSUTIL_FreeM odulel nfo function must be called to deallocate memory containing the list. 
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RETURN VALUE 
NULL — Error in retrieving information from the MDS registry. 


Not NULL — A pointer toa module info structure containing a pointer to an array of zero or more service 
information structures. Each structure contains type information identifying the service description as 
representing certificate library services, data storage library services, and so on. The service descriptions are 
sub-classed into subservice descriptions that describe the attributes and capabilities of a subservice. 


ERRORS 


Errors are described in the CDSA Technical Standard. 


CSSMERR_CSSM_INVALID POINTER 
CSSMERR_CSSM_INVALID_GUID 
CSSM_INVALID_SUBSERVICEID 
CSSMERR_CSSM_MEMORY_ERROR 
CSSMERR_CSSM_NOT_INITIALIZED 
CSSM_ERRCODE_ MDS ERROR 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 


Functions: MDSUTIL_Moduleinstall, MDSUTIL_ModuleUninstall, MDSUTIL_ListModules, 
MDSUTIL_Ge&CredL ocationFromGUID, MDSUTIL_FreeModuld nfo, MDSUTIL_FreeM odule. ist, 
MDSUTIL_ListModuleV anagers, MDSUTIL_GetModuleM anager nfo, MDSUTIL_ModuleManageI nstall, 
MDSUTIL_ModuleManageUninstall, MDSUTIL_Init, MDSUTIL_Tem 
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MDSUTIL_GetModuleManagerI nfo 
NAME 


MDSUTIL_GetM oduleM anager! nfo - Returns descriptive information about the elective module 
manager identified by the GUID or the service mask. 


SYNOPSIS 


#include <mds_util_api.h> 
#include <mds_util_helper.h> 


CSSM_RETURN CSSMAPI MDSUTIL_GetModuleManagerInfo 
(const CSSM_GUID *ModuleGUID, 

CSSM_SERVICE_MASK ServiceType, 
MDSUTIL_MODULE_MANAGER_INFO_PTR *ModuleManagerInfo) 


LIBRARY 


Module Directory Services library (cdsa$mds300_shr.exe) 


PARAMETERS 


ModuleGUID (input) 

A pointer toa GUID identifying the module manager. 
ServiceType (input) 

A unique service mask identifying the module manager. 
ModuleManageriInfo (output) 


A pointer to the returned module manager information. 


DESCRIPTION 


This function returns descriptive information about the elective module manager identified by the GUID or 
the service mask. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. NULL indicates that the routine was unable to get the module manager information. 


ERRORS 


Errors are described in the CDSA Technical Standard. 


CSSMERR_CSSM_INVALID POINTER 
CSSMERR_CSSM_INVALID_GUID 
CSSM_ERRCODE_MDS ERROR 
CSSMERR_CSSM_INVALID_SERVICE_MASK 
CSSM_ERRCODE_MEMORY_ ERROR 
CSSMERR_CSSM_MEMORY_ERROR 
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SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 


Functions: MDSUTIL_Moduleinstall, MDSUTIL_ModuleUninstall, MDSUTIL_ListModules, 
MDSUTIL_Ge&Moduld nfo, MDSUTIL_Ge&CredLocationF romGUID, MDSUTIL_FreeM oduld nfo, 
MDSUTIL_FreeM oduleList, MDSUTIL_ListModuleM anagers, MDSUTIL_ModuleM anageI nstall, 
MDSUTIL_ModuleManagerUninstall, MDSUTIL_Init, MDSUTIL_Term 
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MDSUTIL_Init 
NAME 

MDSUTIL_Init - Initializes the MDS registry in preparation for a series of MDSUTIL operations. 
SYNOPSIS 


#include <mds_util_api.h> 
#include <mds_util_helper.h> 


CSSM_RETURN CSSMAPI MDSUTIL_Init 
(CSSM_BOOL ReadWrite) 


LIBRARY 


Module Directory Services library (cdsa$mds300_shr.exe) 


PARAMETERS 


ReadWrite (input) 


A Boolean flag indicating whether the MDS registry is to be enabled for writing as well as 
reading. CSSM_TRUE indicates that the registry should be enabled for writing. 


DESCRIPTION 


This function initializes the MDS registry in preparation for a series of MDSUTIL operations. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition.The value CSSM_OK 
indicates success. All other values indicate an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 


Functions: MDSUTIL_Moduleinstall, MDSUTIL_ModuleUninstall, MDSUTIL_ListModules, 
MDSUTIL_Ge&Moduld nfo, MDSUTIL_Ge&CredLocationF romGUID, MDSUTIL_FreeM oduld nfo, 
MDSUTIL_FreeM oduleList, MDSUTIL_ListModuleM anagers, MDSUTIL_GetM oduleM anager nfo, 
MDSUTIL_ModuleM anager nstall, MDSUTIL_ModuleManage Uninstall, MDSUTIL_Term 
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MDSUTIL_ListModuleManagers 


NAME 


MDSUTIL_ListM oduleM anagers - Returns the number of module managers and a list of GUIDs 
associated with those module managers. 


SYNOPSIS 


#include <mds_util_api.h> 
#include <mds_util_helper.h> 


CSSM_RETURN CSSMAPI MDSUTIL_ListModuleManagers 
(CSSM_GUID_PTR *ModuleManagerGuids, 
uint32 *NumberOfModuleManagers) 


LIBRARY 


Module Directory Services library (cdsa$mds300_shr.exe) 


PARAMETERS 


ModuleManagerGuids (output) 
A pointer toa list of GUIDs. 
NumberOfModuleManagers (output) 


A pointer to the number of module managers. 


DESCRIPTION 


This function returns the number of module managers and a list of GUI Ds associated with those module 
managers. The caller is responsible for freeing the memory associated with the GUID list. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition.The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 


Errors are described in the CDSA Technical Standard. 


CSSMERR_CSSM_INVALID_POINTER 
CSSM_ERRCODE_MEMORY_ERROR 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 
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Online Help 


Functions: MDSUTIL_Moduldnstall, MDSUTIL_ModuleUninstall, MDSUTIL_ListModules, 
MDSUTIL_Ge&Moduld nfo, MDSUTIL_Ge@CredLocationFromGUID, MDSUTIL_FreeModuld nfo, 
MDSUTIL_FreeModuleList, MDSUTIL_GetModuleManagerI nfo, MDSUTIL_ModuleManage|nstall, 
MDSUTIL_ModuleManagerUninstall, MDSUTIL_Init, MDSUTIL_Term 
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MDSUTIL_ListModules 
NAME 


MDSUTIL_ListM odules - Returns a list containing the GUI D/version/name for each of the currently 
installed service provider modules that provide services in any of the CSSM functional categories 
selected in the usage mask. The MDSUTIL_FreeM oduleList function must be called to deallocate 
memory containing the list. 


SYNOPSIS 


#include <mds_util_api.h> 
#include <mds_util_helper.h> 


CSSM_RETURN CSSMAPI MDSUTIL_ListModules 
(CSSM_SERVICE_MASK UsageMask, 

CSSM_BOOL MatchAll, 

MDSUTIL_LIST_PTR *pList) 


LIBRARY 


Module Directory Services library (cdsa$mds300_shr.exe) 


PARAMETERS 


UsageMask (input) 


A bit mask selecting CSSM functional categories of interest for selecting information about 
potential service provider modules. 


Mat chAll (input) 


A Boolean value to indicate if the add-in has to match all of the conditions expressed in 
UsageMask. TRUE means all conditions must be met. FALSE means one or more conditions 
must be met. 


pList (output) 


Pointer to a list of modules. Each item contains a CSSM_GUID, the module version, anda 
descriptive string name of the module. 


DESCRIPTION 


This function returns a list containing the GUI D/version/name for each of the currently installed service 
provider modules that provide services in any of the CSSM functional categories selected in the usage mask. 
The MDSUTIL_FreeM oduleList function must be called to deallocate memory containing the list. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition.The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 
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CSSM_ERRCODE_MDS_ERROR 
CSSMERR_CSSM_INVALID_POINTER 
CSSM_ERRCODE_INVALID_OUTPUT_POINTER 
CSSM_ERRCODE_MEMORY_ERROR 
CSSMERR_NOT_INITIALIZED 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 


Functions: MDSUTIL_Moduleinstall, MDSUTIL_ModuleUninstall, MDSUTIL_Ge&tM oduld nfo, 
MDSUTIL_GeCredL ocationF romGUID, MDSUTIL_FreeM oduld nfo, MDSUTIL_FreeM odule ist, 
MDSUTIL_ListModuleV anagers, MDSUTIL_GetModuleM anagerI nfo, MDSUTIL_ModuleManageI nstall, 
MDSUTIL_ModuleManageUninstall, MDSUTIL_Init, MDSUTIL_Taem 
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MDSUTIL_Modulelnstall 
NAME 


MDSUTIL_Modulelnstall - Updates the MDS registry with information on the add-in module 


SYNOPSIS 


#include <mds_util_api.h> 
#include <mds_util_helper.h> 


CSSM_RETURN CSSMAPI MDSUTIL_ModuleInstall 
(const char *ModuleName, 


const char *ModuleFileNames, 

const char *ModulePathName, 

const char *ModuleCredentialName, 

const char *ModulCredentialPath, 

const CSSM_GUID *GUID, 

const MDSUTIL_MODULE_INFO *ModuleDescription, 
const void *Reservedl, 

const CSSM_DATA *Reserved2) 

LIBRARY 

Module Directory Services utility API library (cdsaSmds_util_api.olb) 
PARAMETERS 

ModuleName (input) 


Modul 


Modul 


Modul 


Modul 


The name of the add-in module. 
eFileNames (input) 

The name of the file implementing the add-in module. 
ePathName (input) 

The path to the file implementing the add-in module. 
eCredentialName (input) 


The name of the credential file for the add-in module. 


eCredentialPath (input) 
The path to the credential file for the add-in module. 


GUID (input) 


The Globally Unique!D of the add-in module. 


ModuleDescription (input) 


A pointer toa structure that describes the add-in module. 


Reserved! (input) 


Reserved data. 


Reserved2 (input) 


Reserved data. 
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DESCRIPTION 
This function updates the MDS registry with information on the add-in module. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition.The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 


Errors are described in the CDSA Technical Standard. 


CSSMERR_CSSM_INVALID_POINTER 
CSSMERR_DL_OS ACCESS DENIED 

CSSMERR_CSSM_INTERNAL_ERROR 
CSSM_ERRCODE_INTERNAL_ERROR 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 


Functions: MDSUTIL_ModuleUninstall, MDSUTIL_ListModules, MDSUTIL_Ge&tM oduld nfo, 
MDSUTIL_Ge&CredLocationF romGUID, MDSUTIL_FreeM odule nfo, MDSUTIL_FreeM odulez ist, 
MDSUTIL_ListModuleV anagers, MDSUTIL_GetModuleM anager nfo, MDSUTIL_ModuleManageI nstall, 
MDSUTIL_ModuleManagerUninstall, MDSUTIL_Init, MDSUTIL_Taem 
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MDSUTIL_ModuleManagerInstall 


NAME 


MDSUTIL_ModuleM anager! nstall - Updates the MDS registry with information about the 
Extensible Module M anager 


SYNOPSIS 


#include <mds_util_api.h> 
#include <mds_util_helper.h> 


CSSM_RETURN CSSMAPI MDSUTIL_ModuleManagerInstall 
(const char *ModuleManagerName, 


const char *ModuleManagerFileName, 

const char *ModuleManagerPathName, 

const char *ModuleManager CredentialName, 

const char *ModuleManagerCredentialPath, 

const CSSM_GUID *ModuleManagerGuid, 

const MDSUTIL_MODULE_MANAGER_INFO *ModuleManagerDescription, 
const void *Reservedl, 

const CSSM_DATA *Reserved2) 

LIBRARY 


Module Directory Services utility API library (cdsa$Smds_util_api.olb) 


PARAMETERS 


ModuleManagerName (input) 


A pointer to the name of the Extensible Module Manager (EMM). 


ModuleManagerFileName (input) 

A pointer to the filename of the E xtensible Module M anager. 
ModuleManagerPathname (input) 

A pointer to the directory path to the file implementing the EMM. 
ModuleManagerCredentialName (input) 


A pointer to the name of the credential file of the EMM. 


ModuleManagerCredentialPath (input) 
A pointer to the directory path to the credential file of the EMM. 
ModuleManagerGuid (input) 


A pointer to the Globally Unique!D of the EMM. 


ModuleManagerDescription (input) 


A pointer to the structure that describes the EMM. 


DESCRIPTION 
This function updates the MDS registry with information about the Extensible Module M anager. 
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RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition.The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 


Errors are described in the CDSA Technical Standard. 


CSSMERR_CSSM_INVALID_POINTER 
CSSMERR_CSSM_INTERNAL_ERROR 
CSSMERR_CSSM_FUNCTION_ FAILED 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 


Functions: MDSUTIL_Moduleinstall, MDSUTIL_ModuleUninstall, MDSUTIL_ListModules, 
MDSUTIL_Ge&Moduld nfo, MDSUTIL_Ge&CredLocationF romGUID, MDSUTIL_FreeModuld nfo, 
MDSUTIL_FreeModuleList, MDSUTIL_ListModuleV anagers, MDSUTIL_GetM oduleVanage'| nfo, 
MDSUTIL_ModuleManagerUninstall, MDSUTIL_Init, MDSUTIL_Term 
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MDSUTIL_ModuleManager Uninstall 


NAME 


MDSUTIL_ModuleM anagerU ninstall - Removes from the MDS registry the information associated 
with the Globally Unique !D of the EMM 


SYNOPSIS 
#include <mds_util_api.h> 
#include <mds_util_helper.h> 


CSSM_RETURN CSSMAPI MDSUTIL_ModuleManagerUninstall 
(const CSSM_GUID *ModuleManagerGuid) 


LIBRARY 


Module Directory Services utility API library (cdsaSmds_util_api.olb) 


PARAMETERS 


ModuleManagerGuid (input) 
A pointer to the Globally Unique!D of the Extensible M odule M anager. 


DESCRIPTION 


This function removes from the MDS registry the information associated with the Globally Unique ID of the 
EMM. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition.The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 


Errors are described in the CDSA Technical Standard. 


CSSMERR_CSSM_INVALID_GUID 
CSSMERR_CSSM_FUNCTION_FAILED 
CSSM_ERRCODE_MDS ERROR 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 
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Online Help 


Functions: MDSUTIL_Moduldnstall, MDSUTIL_ModuleUninstall, MDSUTIL_ListModules, 
MDSUTIL_Ge&Moduld nfo, MDSUTIL_Ge@CredLocationFromGUID, MDSUTIL_FreeModuld nfo, 
MDSUTIL_FreeModuleList, MDSUTIL_ListModuleM anagers, MDSUTIL_GetM oduleVanage'! nfo, 
MDSUTIL_ModuleManagerinstall, MDSUTIL_Init, MDSUTIL_Term 
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MDSUTIL_ModuleUninstall 


NAME 


MDSUTIL_ModuleUninstall - Removes from the MDS registry the information associated with 
GUID 


SYNOPSIS 
#include <mds_util_api.h> 
#include <mds_util_helper.h> 


CSSM_RETURN CSSMAPI MDSUTIL_ModuleUninstall 
(const CSSM_GUID *ModuleGUID) 


LIBRARY 


Module Directory Services utility API library (cdsaSmds_util_api.olb) 


PARAMETERS 


ModuleGUID (input) 
The Globally Unique!D of the add-in module. 


DESCRIPTION 


This function removes from the MDS registry the information associated with GUID. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 


Errors are described in the CDSA Technical Standard. 
CSSMERR_CSSM_MEMORY_ERROR 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 


Functions: MDSUTIL_Moduldinstall, MDSUTIL_ListM odules, MDSUTIL_GetM oduld nfo, 
MDSUTIL_Ge&CredL ocationFromGUID, MDSUTIL_FreeModuld nfo, MDSUTIL_FreeModule. ist, 
MDSUTIL_ListModuleV anagers, MDSUTIL_GetModuleManager| nfo, MDSUTIL_ModuleManageI nstall, 
MDSUTIL_ModuleManagerUninstall, MDSUTIL_Init, MDSUTIL_Taem 
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MDSUTIL_Term 


NAME 
MDSUTIL_Term - Closes the MDS registry after a series of operations. 


SYNOPSIS 


#include <mds_util_api.h> 
#include <mds_util_helper.h> 
void CSSMAPI MDSUTIL_Term() 


LIBRARY 


Module Directory Services library (cdsa$mds300_shr.exe) 


PARAMETERS 


None 


DESCRIPTION 


This function closes the MDS registry after a series of operations. 


RETURN VALUE 


None 


ERRORS 
Errors are described in the CDSA Technical Standard. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 


Functions: MDSUTIL_Moduleinstall, MDSUTIL_ModuleUninstall, MDSUTIL_ListModules, 
MDSUTIL_Ge&Moduld nfo, MDSUTIL_Ge&CredLocationFromGUID, MDSUTIL_FreeModuld nfo, 
MDSUTIL_FreeM oduleList, MDSUTIL_ListModuleM anagers, MDSUTIL_GetM oduleM anager! nfo, 
MDSUTIL_ModuleM anager nstall, MDSUTIL_ModuleManageUninstall, MDSUTIL_Init 
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ObtainPrivateKeyF romPublicKey 
NAME 


ObtainPrivateK eyF romP ublicK ey: CSSM_CSP_ObtainPrivateK eyF romP ublick ey, 
CSP_ObtainPrivateK eyF romP ublick ey - Convert public key to private key (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_CSP_ObtainPrivateKeyFromPublicKkey 
(CSSM_CSP_HANDLE CSPHandle 

const CSSM_KEY *PublicKey, 

CSSM_KEY_PTR PrivateKey) 

SPI: 
CSSM_RETURN CSSMCSPI CSP_ObtainPrivateKeyFromPublicKey 
(CSSM_CSP_HANDLE CSPHandle, 
const CSSM_KEY *PublicKey, 
CSSM_KEY_PTR PrivateKey) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 
CSPHandle (input) 

The handle that describes the module to perform this operation. 
PublicKkey (input) 

The public key corresponding to the private key being sought. 
PrivateKey (output) 


A reference to the private key corresponding to the public key. 


DESCRIPTION 


Given a public key this function returns a reference to the private key. The private key and its associated 
passphrase can be used as an input to any function requiring a private key value. 


NOTES 


The KeyData field of the CSSM_KEY structureis allocated by the CSP. The application is required to free this 
memory using the cSSM_FreeKey () (CSSM API), or CSP_FreeKey() (CSP SPI), function or with the memory 
functions registered for the cSPHandle. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 
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ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CSP_PRIVATE_KEY_NOT_FOUND 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 
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PassThrough 


NAME 
PassThrough: CSSM_CSP_PassThrough, CSP_PassThrough - Extend crypto functionality (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_CSP_PassThrough 
(CSSM_CC_HANDLE CCHandle, 

uint32 PassThroughId, 

const void *InData, 

void **OutData) 

SPI: 
CSSM_RETURN CSSMCSPI CSP_PassThrough 
(CSSM_CSP_HANDLE CSPHandle, 
CSSM_CC_HANDLE CCHandle, 
const CSSM_CONTEXT *Context, 
uint32 PassThroughId, 

const void *InData, 

void **OutData) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


API PARAMETERS 


CCHandle (input) 

The handle that describes the context of this cryptographic operation. 
PassThroughId (input) 

An identifier specifying the custom function to be performed. 
InData (input) 

A pointer toa module, implementation-specific structure containing the input data. 
OutData (output) 


A pointer to a module, implementation-specific structure containing the output data. The 
service provider will allocate the memory for this structure. The application should free the 
memory for the structure. 


SPI PARAMETERS 
CSPHandle (input) 

Handle of the CSP supporting the PassThrough function. 
Context (input) 


Pointer to CSSM_CONTEXT structure that describes the attributes with this custom 
context structure. 
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DESCRIPTION 


The CSSM_CSP_PassThrough () (CSSM API), or CSP_PassThrough() (CSP SPI), function is provided to allow 
CSP developers to extend the crypto functionality of the CSSM API. 


NOTES 


The CSP_EventNotify() function is used by the CSSM Core to interact with the CSP module. 


Because this function is only exposed to CSSM as a function pointer, the function name internal to the CSP 
can be assigned at the discretion of the CSP module developer. However, the parameter list and return value 
types must match those defined for this function. 


The error codes given in this section constitute the generic error codes, which may be used by all CSP 
libraries to describe common error conditions. CSP module developers may also define their own 
module-specific error codes. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CSP_INVALID_PASSTHROUGH_ID 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 
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QueryKeySizel nBits 


NAME 


QueryK eySizel nBits: CSSM_QueryK eySizel nBits, CSP_QueryK eySizel nBits - Get CSP logical and 
effective sizes (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_QueryKeySizeInBits 
(CSSM_CSP_HANDLE CSPHandle, 

CSSM_CC_HANDLE CCHandle, 

const CSSM_KEY *Key, 

CSSM_KEY_SIZE_PTR KeySize) 

BPI¢ 
CSSM_RETURN CSSMCSPI CSP_QueryKeySizeInBits 
(CSSM_CSP_HANDLE CSPHandle, 

CSSM_CC_HANDLE CCHandle, 

const CSSM_CONTEXT *Context, 

const CSSM_KEY *Key, 

CSSM_KEY_SIZE_PTR KeySize) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


API PARAMETERS 


CSPHand1le (input/optional) 


The handle that describes the Cryptographic Service Provider module used to perform this 
function. 


For the API, this parameter is ignored if a valid cryptographic context handle is specified. 
CCHand1e (input/optional) 


A handle toa context that describes a cryptographic operation. The cryptographic context 
should contain a handle to the CSP that is being queried and the key about which key-size 
information is being requested. 


Key (input/optional) 


A pointer toa CSSM_KEY structure containing the key about which key-size information is 
being requested. This parameter is ignored if a valid cryptographic context handle is 
specified. 


KeySize (output) 


Pointer toa CSSM_KEY_SIZE data structure. The logical and effective sizes (in bits) for the 
key are returned in this structure. 


For the API, if no context handle is provided, only the CSSM_KEY_SIZE 
LogicalKeySizeInBits field is set. 
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SPI PARAMETERS 


Context (input) 
Pointer to CSSM_CONTEXT structure that describes the attributes with this context. 


DESCRIPTION 


This function queries a Cryptographic Service Provider (CSP) for the logical and effective sizes of a specified 
Key. 


The Cryptographic Service Provider (handle) and the key can be specified either in the cryptographic context 
or as parameters to the function call. If a valid cryptographic context handle parameter is specified, the CSP 
handle and key parameters are ignored. 


RETURN VALUE 

A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 

ERRORS 

Errors are described in the CDSA Technical Standard. 


CSSMERR_CSP_QUERY_SIZE_UNKNOWN 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 

CSSM_GenerateRandom, CSSM_GenerateKeyPair, CSSM_GmeratkKey 
Functions for the CSP SPI: 

CSP_GmerateRandom, CSP_GenerateKeyPair, CSP_GenerateK ey 
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QuerySize 
NAME 
QuerySize: CSSM_QuerySize, CSP_QuerySize - Get size of the output data (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 
CSSM_RETURN CSSMAPI CSSM_QuerySize 


(CSSM_CC_HANDLE CCHandle, 

CSSM_BOOL Encrypt, 

uint32 QuerySizeCount, 
CSSM_QUERY_SIZE_DATA_PTR DataBlockSizes) 
SPI: 
CSSM_RETURN CSSMCSPI CSP_QuerySize 
(CSSM_CSP_HANDLE CSPHandle, 
CSSM_CC_HANDLE CCHandle, 

const CSSM_CONTEXT *Context, 

CSSM_BOOL Encrypt, 

uint32 QuerySizeCount, 
CSSM_QUERY_SIZE_DATA_PTR DataBlockSizes) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


API PARAMETERS 


CCHandle (input) 


The handle for an encryption and decryption context. 


Encrypt (input) 


A boolean indicating whether encryption is the operation for which the output data size 
should be calculated. If CSSM_TRUE, the operation is encryption. lf CSSM_FALSE the 
operation is decryption. 


QuerySizeCount (input) 
The number of entries in the array of DataBlockSizes. 
DataBlockSizes (input/output) 


An array of data block input sizes and corresponding entries for the data block output sizes 
that are returned by this function. 


SPI PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform calls to CSSM for the memory functions managed by CSSM. 


Context (input) 
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Pointer to CSSM_CONTEXT structure that describes the attributes with this context. 


DESCRIPTION 


This function queries for the size of the output data for a cryptographic operation. If the context is an 
encryption or decryption context type then the Encrypt parameter will determine which operation is being 
performed. If Encrypt is set toCSSM_TRUE then it is an encrypt operation, otherwise it is a decrypt 
operation. For all other context types the Encrypt parameter is ignored. This function can also be used to 
query the output size requirements for the intermediate steps of a staged cryptographic operation. There may 
be algorithm-specific and token-specific rules restricting the lengths of data following data update calls. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CSP_QUERY_SIZE_UNKNOWN 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 


Functions for the CSSM API: 


CSSM_EncryptData, CSSM_EncryptDataU pdate CSSM_DecryptData, CSSM_DecryptDataU pdate 
CSSM_SignData, CSSM VerifyData, CSSM_DigestData, CSSM_GmerateMac 


Functions for the CSP SPI: 


CSP_EncryptData, CSP_EncryptDataU pdate, CSP_DecryptData, CSP_DecryptDataU pdate, CSP_SignData, 
CSP_VerifyData, CSP_DigestData, CSP_GenerateM ac 
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RetrieveC ounter 


NAME 


RetrieveCounter: CSSM_RetrieveCounter, CSP_RetrieveCounter - Get the value of a tamper 
resistant clock (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_RetrieveCounter 
(CSSM_CSP_HANDLE CSPHandle, 
CSSM_DATA_PTR Counter) 

SPI: 
CSSM_RETURN CSSMCSPI CSP_RetrieveCounter 
(CSSM_CSP_HANDLE CSPHandle, 
CSSM_DATA_PTR Counter) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform this function. If a NULL handleis specified, CSSM returns error. 


Counter (output) 


Pointer to CSSM_DATA structure that contains data of the tamper resistant clock/counter 
of the cryptographic device. 


DESCRIPTION 


This function returns the value of a tamper resistant clock/counter of the cryptographic device. 


NOTES ON SPI 


The output is returned to the caller as specified in Buffer Management for Cryptographic Services. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


None specific to this call. 
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SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 
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RetrieveU niqueld 


NAME 
RetrieveUniquel d: CSSM_RetrieveU niquel d, CSP_RetrieveU niquel d - Get identifier (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_RetrieveUniqueld 
(CSSM_CSP_HANDLE CSPHandle, 

CSSM_DATA_PTR UniquelID) 

SPI: 
CSSM_RETURN CSSMCSPI CSP_RetrieveUniqueld 
(CSSM_CSP_HANDLE CSPHandle, 

CSSM_DATA_PTR UniquelID) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform this function. If a NULL handleis specified, CSSM returns error. 


UniqueID (output) 


Pointer to CSSM_DATA structure that contains data that uniquely identifies the 
cryptographic device. 


DESCRIPTION 


This function returns an identifier that could be used to uniquely differentiate the cryptographic device from 
all other devices from the same vendor or different vendors. 


NOTES ON SPI 


The output is returned to the caller as specified in Buffer Management for Cryptographic Services. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


None specific to this call. 
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SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 
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SignData 
NAME 
SignData: CSSM_SignData, CSP_SignData - Sign all buffer data (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 
CSSM_RETURN CSSMAPI CSSM_SignData 
(CSSM_CC_HANDLE CCHandle, 

const CSSM_DATA *DataBufs, 

uint32 DataBufCount, 
CSSM_ALGORITHMS DigestAlgorithm, 
CSSM_DATA_PTR Signature) 

SPI: 
CSSM_RETURN CSSMCSPI CSP_SignData 
(CSSM_CSP_HANDLE CSPHandle, 
CSSM_CC_HANDLE CCHandle, 

const CSSM_CONTEXT *Context, 
const CSSM_DATA *DataBufs, 

uint32 DataBufCount, 
CSSM_ALGORITHMS DigestAlgorithm, 
CSSM_DATA_PTR Signature) 


LIBRARY 


Common Security Services M anager library (cdsa$incssm300_shr.exe) 


API PARAMETERS 


CCHandle (input) 


The handle that describes the context of this cryptographic operation used to link to the 
CSP-managed information. 


Dat aBufs (input) 

A pointer to a vector of CSSM_DATA structures that contain the data to be signed. 
Dat aBufCount (input) 

The number of DataBufs to be signed. 


DigestAlgorithm (input) 


If signing just a digest, specifies the type of digest. In this case, the context should only 
specify the encryption algorithm. If not signing just a digest, it must be 
CSSM_ALGID_NONE. In this case, the context should specify the combination 
digest/encryption algorithm. 


Signature (output) 
A pointer tothe CSSM_DATA structure for the signature. 
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SPI PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform up calls to CSSM for the memory functions managed by CSSM. 


Context (input) 
Pointer to CSSM_ CONTEXT structure that describes the attributes with this context. 


DESCRIPTION 


This function signs all data contained in the set of input buffers using the private key specified in the context. 
The CSP can require that the cryptographic context include access credentials for authentication and 
authorization checks when using a private key or a secret key. 


Signing can include digesting the data and encrypting the digest or signing just the digest (already calculated 
by the application). If digesting the data and encrypting the digest, then the context should specify the 
combination digest/encryption algorithm (for example, CSSM_ALGID_MD5WithRSA). In this case, the 
DigestAlgorithm parameter must be set to CSSM_ALGID_NONE. If signing just the digest, then the 
context should specify just the encryption algorithm and the DigestAlgorithm parameter should specify the 
type of digest (for example, CSSM_ALGID_MD5). Also, DataBufCount must be 1. 


If the signing algorithm is not reversible or strictly limits the size of the signed data, then the algorithm can 
specify signing without digesting. In this case, the sign operation is performed on the input data and the size 
of the input data is restricted by the service provider. 


NOTES ON API 


The output is returned to the caller either by filling the caller-specified buffer or by using the application's 
declared memory allocation functions to allocate buffer space. To specify a specific, preallocated output buffer, 
the caller must provide an array of one or more CSSM_DATA structures each, containing a Length field value 
greater than zero and a non-NULL data pointer field value. To specify automatic output buffer allocation by 
the CSP, the caller must provide an array of one or more CSSM_DATA structures, each containing a Length 
field value equal to zero and a NULL data pointer field value. The application is always responsible for 
deallocating the memory when it is no longer needed. 


NOTES ON SPI 


The output is returned to the caller as specifed in Buffer Management for Cryptographic Services. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CSP_OUTPUT_LENGTH_ERROR 
CSSMERR_CSP_INVALID_DIGEST_ALGORITHM 


410 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 

CSSM_VerifyData, CSSM_SignDatal nit, CSSM_SignDataUpdate CSSM_SignDataF inal 
Functions for the CSP SPI: 

CSP_VerifyData, CSP_SignDatal nit, CSP_SignDataU pdate, CSP_SignDataFinal 


411 


SignDataF inal 


NAME 


SignDataFinal: CSSM_SignDataFinal, CSP_SignDataF inal - Complete the final stage of the sign 
data (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_SignDataFinal 
(CSSM_CC_HANDLE CCHandle, 
CSSM_DATA_PTR Signature) 

SP Es 
CSSM_RETURN CSSMCSPI CSP_SignDataFinal 
(CSSM_CSP_HANDLE CSPHandle, 
CSSM_CC_HANDLE CCHandle, 

CSSM_DATA_PTR Signature) 


LIBRARY 


Common Security Services M anager library (cdsa$incssm300_shr.exe) 


API PARAMETERS 


CCHandle (input) 


The handle that describes the context of this cryptographic operation used to link to the 
CSP-managed information. 


Signature (output) 
A pointer tothe CSSM_DATA structure for the signature. 


SPI PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform up calls to CSSM for the memory functions managed by CSSM. 


DESCRIPTION 


This function completes the final stage of the sign data function. 


NOTES ON API 


The output is returned to the caller either by filling the caller-specified buffer or by using the application's 
declared memory allocation functions to allocate buffer space. To specify a specific, preallocated output buffer, 


the caller must provide an array of one or more CSSM_DATA structures, each containing a Length field value 


greater than zero and a non-NULL data pointer field value. To specify automatic output buffer allocation by 
the CSP, the caller must provide an array of one or more CSSM_DATA structures, each containing a Length 
field value equal to zero and a NULL data pointer field value. The application is always responsible for 
deallocating the memory when it is no longer needed. 
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NOTES ON SPI 


The output is returned to the caller as specifed in Buffer Management for Cryptographic Services. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CSP_OUTPUT_LENGTH_ERROR 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 

CSSM_SignData, CSSM_SignDatal nit, CSSM_SignDataU pdate 
Functions for the CSP SPI: 

CSP_SignData, CSP_SignDatal nit, CSP_SignDataU pdate 
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SignDatal nit 


NAME 
SignDatal nit: CSSM_SignDatal nit, CSP_SignDatal nit - Initialize the staged sign data (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_SignDataInit 
(CSSM_CC_HANDLE CCHandle) 

SP Es 
CSSM_RETURN CSSMCSPI CSP_SignDataInit 
(CSSM_CSP_HANDLE CSPHandle, 
CSSM_CC_HANDLE CCHandle, 

const CSSM_CONTEXT *Context) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


API PARAMETERS 


CCHandle (input) 


The handle that describes the context of this cryptographic operation used to link to the 
CSP-managed information. 


SPI PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform up calls to CSSM for the memory functions managed by CSSM. 


Context (input) 
Pointer to CSSM_CONTEXT structure that describes the attributes with this context. 


DESCRIPTION 


This function initializes the staged sign data function. 


For staged operations, a combination operation selecting both a digesting algorithm and a signing algorithm 
must be specified. 


The CSP can require that the cryptographic context include access credentials for authentication and 
authorization checks when using a private key or a secret key. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 
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ERRORS 
Errors are described in the CDSA Technical Standard. 


None specific to this call. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 

CSSM_SignData, CSSM_SignDataUpdate, CSSM_SignDataFinal 
Functions for the CSP SPI: 

CSP_SignData, CSP_SignDataU pdate, CSP_SignDataF inal 
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SignDataU pdate 


NAME 


SignDataU pdate: CSSM_SignDataU pdate, CSP_SignDataU pdate - Continue the staged signing 
process input buffer data (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_SignDataUpdate 
(CSSM_CC_HANDLE CCHandle, 

const CSSM_DATA *DataBufs, 

uint32 DataBufCount) 

SPI: 
CSSM_RETURN CSSMCSPI CSP_SignDataUpdate 
(CSSM_CSP_HANDLE CSPHandle, 
CSSM_CC_HANDLE CCHandle, 

const CSSM_DATA *DataBufs, 

uint32 DataBufCount) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


API PARAMETERS 


CCHandle (input) 


The handle that describes the context of this cryptographic operation used to link to the 
CSP-managed information. 


DataBufs (input) 

A pointer toa vector of CSSM_DATA structures that contain the data to be operated on. 
Dat aBufCount (input) 

The number of DataBufs to be signed. 


SPI PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform calls to CSSM for the memory functions managed by CSSM. 


DESCRIPTION 


This function continues the staged signing process over all data contained in the set of input buffers. Signing 
is performed using the private key specified in the context. 
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RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 


indicates success. All other values represent an error condition. 


SEE ALSO 


Books 


Inte CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 

CSSM_SignData, CSSM_SignDatal nit, CSSM_SignDataF inal 
Functions for the CSP SPI: 

Funcitons: CSP_SignData, CSP_SignDatal nit, CSP_SignDataF inal 
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TP_ApplyCriToDb 


NAME 


TP_ApplyCriToDb: CSSM_TP_ApplyCrIToDb - Update persistent storage (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 


CSSM_RETURN CSSMAPI CSSM_TP_ApplyCr1lToDb 


(CSSM_TP_HANDLE 
HAN 


E 


TPHandle, 


CSSM_CL_ 


CSSM_CSP_HANDLE 
const CSSM_E 


CODED_CRL *Crli 


CLHandle, 
CSPHandle, 
ToBeApplied, 


const CSSM_CERTGROUP *SignerCertGroup, 


const CSSM_TP_VERIFY_CONTEX 


*ApplyCrlVerifyContext, 


CSSM_TP_VERIFY_CONTEXT_RESULT_PTR ApplyCrlVerifyResult) 


SPL 


CSSM_RETURN CSS 


(CSSM_TP_HANDLE 
HAN 


CSSM_CL_ 


E 


TPI TP_ApplyCrl1ToDb 
TPHandle, 


CLHandle, 


CSSM_CSP_HANDLE 
const CSSM_E 


CSPHandle, 


CODED_CRL *CrlToBeApplied, 


const CSSM_CERTGROUP *SignerCertGroup, 


const CSSM_TP_VERIFY_CONTEX 


*ApplyCrlVerifyContext, 


CSSM_TP_VERIFY_CONTEXT_RESULT_PTR ApplyCrlVerifyResult) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


TPHandle (input) 


The handle that describes the add-in trust policy module used to perform this function. 


CLHand1le (input/optional) 


The handle that describes the add-in certificate library module that can be used to 
manipulate the CRL as it is applied to the data store and to manipulate the certificates 
effected by the CRL, if required. If no certificate library module is specified, the TP module 
uses an assumed CL module, if required. 


CSPHand1le (input/optional) 


The handle referencing a Cryptographic Service Provider to be used to verify signatures on 
the CRL determining whether totrust the CRL and apply it to the data store. The TP 
module is responsible for creating the cryptographic context structures required to perform 
the verification operation. If no CSP is specified, the TP module uses an assumed CSP to 
perform these operations. If optional, the caller will set this value to 0. 


Cr1ToBeApplied (input) 
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A pointer toa structure containing the encoded certificate revocation list to be applied to the 
data store. The CRL type and encoding are included in this structure. 


SignerCertGroup (input) 


A pointer tothe CSSM_CERTGROUP structure containing one or more related certificates 
that partially or fully represent the signer of the certificate revocation list. The first 
certificate in the group is the target certificate representing the CRL signer. Use of 
subsequent certificates is specific to the trust domain. For example, in a hierarchical trust 
model, subsequent members are intermediate certificates of a certificate chain. 


ApplyCrlVerifyContext (input/optional) 


A structure containing credentials, policy information, and contextual information to be 
used in the verification process. All of the input values in the context are optional. The 
service provider can define default values or can attempt to operate without input for all the 
other fields of this input structure. The operation can fail if a necessary input value is 
omitted and the service module can not define an appropriate default value. 


ApplyCrlVerifyResult (output/optional) 


A pointer to a structure containing information generated during the verification process. 
The information can include: 


Evidence (output/opti onal) 


NumberOfEvidences (output/opti onal) 


DESCRIPTION 


This function updates persistent storage to reflect entries in the certificate revocation list. The TP module 
determines whether the memory-resident CRL is trusted, and if it should be applied to one or more of the 

persistent databases. Side effects of this function can include saving a persistent copy of the CRL ina data 
store, or removing certificate records from a data store. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 

Errors are described in the CDSA Technical Standard. 
CSSMERR_TP_INVALID_CL_HANDLE 
CSSMERR_TP_INVALID_CSP_HANDLE 
CSSMERR_TP_INVALID_CRL_TYPE 
CSSMERR_TP_INVALID_CRL_ENCODING 
CSSMERR_TP_INVALID_CRL_ POINTER 
CSSMERR_TP_INVALID_CRL 
CSSMERR_TP_INVALID_CERTGROUP_POINTER 
CSSMERR_TP_INVALID_CERTGROUP 
CSSMERR_TP_INVALID_ CERTIFICATE 
CSSMERR_TP_INVALID_ACTIO 
CSSMERR_TP_INVALID_ACTION_DATA 
CSSMERR_TP_VERIFY_ACTION_FATLED 
CSSMERR_TP_INVALID_CRLGROUP_POINTER 
CSSMERR_TP_INVALTID_CRLGROUP 
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CSSMERR_TP_INVALID_CRL_ AUTHORITY 
CSSMERR_TP_INVALID_CALLERAUTH_ CONTEXT POINTER 
CSSMERR_TP_INVALID_POLICY_IDENTIFIERS 
CSSMERR_TP_INVALID_TIMESTRING 
CSSMERR_TP_INVALID_STOP_ON_POLICY 
CSSMERR_TP_INVALID_ CALLBACK 
CSSMERR_TP_INVALID_ANCHOR_CERT 
CSSMERR_TP_CERTGROUP_INCOMPLETE 
CSSMERR_TP_INVALID_DL_HANDLE 
CSSMERR_TP_INVALID_DB HANDLE 
CSSMERR_TP_INVALID_DB_ LIST POINTER 
CSSMERR_TP_INVALID_DB_ LIST 
CSSMERR_TP_AUTHENTICATION_FAILED 
CSSMERR_TP_INSUFFICIENT CREDENTIALS 
CSSMERR_TP_NOT_TRUSTED 
CSSMERR_TP_CERT_REVOKED 
CSSMERR_TP_CERT SUSPENDED 
CSSMERR_TP_CERT_EXP TIRED 
CSSMERR_TP_CERT_NOT_VALID_YET 
CSSMERR_TP_INVALID_CERT_AUTHORITY 
CSSMERR_TP_INVALID_ SIGNATURE 
CSSMERR_TP_INVALTID_NAMEF 
CSSMERR_TP_CERTIFICATE CANT OPERATE 
SEE ALSO 

Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 

CSSM_CL_CrlGeFirstlten, CSSM_CL_CrlGetNextl tem, CSSM_DL_CertRevoke 
Functions for the TP SPI: 

CL_CrilGetFirstlten, CL_CrlG&Nextlten, DL_CertRevoke 
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TP_CertCreateTemplate 


NAM 


TP_CertCreateT emplate: CSSM_TP_CertCreateTemplate - Allocate and initialize template memory 
(CDSA) 


SYNOPSIS 


#includ 


APT: 


e <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_TP_CertCreateTemplat 


(CSSM_TP_HANDLE TPHandle, 


_ HANDLE CLHandle, 


CSSM_CL 


uint32 


NumberOfFields, 


const CSSM_FIELD *CertFields, 
CSSM_DATA_PTR CertTemplate) 


CSSM_RETURN CSSMTPI TP_CertCreateTemplat 
(CSSM_TP_HANDLE TPHandle, 


CSSM_CL_ 


HANDLE CLHandle, 


uint32 


NumberOfFields, 


const CSSM_FIELD *CertFields, 
CSSM_DATA_PTR CertTemplate) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


TPHand]l 


CLHand] 


le (input) 
The handle that describes the add-in trust policy module used to perform this function. 


le (input) 
The handle that describes the certificate library module used to perform this function. 


NumberOfFields (input) 


The number of certificate field values specified in the certFields. 


CertFields (input) 


A pointer to an array of OI D/value pairs that identifies the field values to initialize a new 
certificate. 


CertTemplate (output) 


A pointer toa CSSM_DATA structure that will contain the unsigned certificate template as 
a result of this function. 
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DESCRIPTION 


This function allocates and initializes memory for an encoded certificate template output in 
CertTemplate->Data. The template values are specified by the input Ol D/value pairs contained in 
CertFields. The initialization process includes encoding all certificate field values according to the 
certificate type and certificate template encoding supported by the trust policy library module. The 
CertTemplate output is an unsigned certificate template in the format supported by the TP. 


The memory for Cert Template->Data is allocated by the service provider using the calling application's 
memory management routines. The application must deallocate the memory. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_TP_INVALID_CL_HANDLE 
CSSMERR_TP_INVALID_FIELD_POINTER 
CSSMERR_TP_UNKNOWN_TAG 
CSSMERR_TP_INVALID_NUMBER_OF_FIELDS 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 
CSSM_TP_CetGeAllTemplateFidds, CSSM_TP_CertSign 
Functions for the TP SPI: 

TP_CertGetAllTemplateFidds, TP_CertSign 
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TP_CertGetAllTemplateF ields 
NAME 


TP_CertGetAllTemplateFields: CSSM_TP_CertGetAllTemplateFields - Get CertTemplate field 
values (CDSA) 


SYNOPSIS 


#include <cssm.h> 


APT: 
CSSM_RETURN CSSMAPI CSSM_TP_CertGetAllTemplateFields 
(CSSM_TP_HANDLE TPHandle, 


CSSM_CL_HANDLE CLHandle, 
const CSSM_DATA *CertTemplate, 
uint32 *NumberOfFields, 


CSSM_FIELD_PTR *CertFields) 


SPI 

CSSM_RETURN CSSMTPI TP_CertGetAllTemplateFields 
(CSSM_TP_HANDLE TPHandle, 

CSSM_CL_HANDLE CLHandle, 


const CSSM_DATA *CertTemplate, 
uint32 *NumberOfFields, 
CSSM_FIELD_PTR *CertFields) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


TPHandle (input) 


The handle that describes the add-in trust policy module used to perform this function. 


CLHandle (input) 
The handle that describes the certificate library module used to perform this function. 
CertTemplate (input) 


A pointer tothe CSSM_DATA structure containing the packed, encoded certificate 
template. 


NumberOfFields (output) 
The length of the output array of fields. 
CertFields (output) 


A pointer to an array of CSSM_FIELD structures which contains the OI Ds and values of the 
fields of the input certificate template. 


DESCRIPTION 


This function extracts and returns all field values from Cert Template. The Cert Template parameter is an 
unsigned certificate template in the format supported by the TP. Fields are returned as a set of Ol D-value 
pairs. The OID identifies the TP certificate template field and the data format of the value extracted from 
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that field. The Trust Policy module defines and uses a preferred data format for returning field values from 
this function. Memory for the CertFields output is allocated by the service provider using the calling 
application's memory management routines. The application must deallocate the memory, by calling 
CSSM_CL_FreeFields() (CSSM API), or CL_FreeFields() (TP SPI). 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_TP_INVALID_CL_HANDLE 
CSSMERR_TP_INVALID_FIELD_POINTER 
CSSMERR_TP_UNKNOWN_FORMAT 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 
CSSM_TP_CetCreatelemplate CSSM_TP_CertSign 
Functions for the TP SPI: 

TP_CertCreateTemplate, TP_CertSign 
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TP_CertGroupConstruct 
NAME 


T 


P_CertGroupConstruct: CSSM_TP_CertGroupConstruct - Construct credential (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_R 


ETU. 


(CSSM_TP_| 


CSSM_CL 


RN CSSMAPI CSSM_TP_CertGroupConstruct 
HANDLE TPHandle, 


HANDLE CLHandle, 


CSSM_CSP_ 
const CSSM_DL_DB_LIST *DBList, 


HANDLE CSPHandle, 


const void *ConstructParams, 
const CSSM_CERTGROUP *CertGroupFrag, 


CSSM_C]I 
SPI: 
CSSM_R 


ETU. 


(CSSM_TP_| 


CSSM_CL 


ERTGROUP_PTR *CertGroup) 


RN CSSMTPI TP_CertGroupConstruct 
HANDLE TPHandle, 


HANDLE CLHandle, 


CSSM_CSP_ 
const CSSM_DL_DB_LIST *DBList, 


HANDLE CSPHandle, 


const void *ConstructParams, 
const CSSM_CERTGROUP *CertGroupFrag, 


CSSM_Cl 


ERTGROUP_PTR *CertGroup) 


LIBRARY 


Common Security Services M anager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


TPHandle (input) 


The handle to the trust policy module to perform this operation. 


CLHand1le (input/optional) 


The handle to the certificate library module that can be used to manipulate and parse 
values in stored in the certgroup certificates. If no certificate library module is specified, the 
TP module uses an assumed CL module. 


CSPHandle (input./optional) 


A handle specifying the Cryptographic Service Provider to be used to verify certificates as 
the certificate group is constructed. If the a CSP handle is not specified, the trust policy 
module can assume a default CSP. If the module cannot assume a default, or the default 
CSP is not available on the local system, an error occurs. 


DBList (input) 


A list of handle pairs specifying a data storage library module and a data store, identifying 
certificate databases containing certificates (and possibly other security objects) that are 
managed by that module. certificates (and possibly other security objects). The data stores 
should be searched to complete construction of a semantically-related certificate group. 


ConstructParams (input/optional) 
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A pointer to data that can be used by the add-in trust policy module in constructing the 
Cert Group.Thesemanticsofthisparameteraredef inedby the trust policy and the credential 
model supported by that policy. The input parameter can consist of a set of values, each 
guiding some aspect of the construction process. Parameter values can: 


e Limit the certificates that are added to the constructed set. 
e Identify other sources of certificates for inclusion in the constructed set. 
CertGroupFrag (input) 


A list of certificates that form a possibly incomplete set of certificates. The first certificate in 
the group represents the target certificate for which a group of semantically related 
certificates will be assembled. Subsequent intermediate certificates can be supplied by the 
caller. They need not be in any particular order. 


CertGroup (output) 


A pointer to a complete certificate group based on the original subset of certificates and the 
certificate data stores. The CSSM_CERTGROUP and its sub-structure is allocated by the 
service provider and must be deallocated by the application. 


DESCRIPTION 


This function builds a collection of certificates that together make up a meaningful credential for a given trust 
domain. For example, in a hierarchical trust domain, a certificate group is a chain of certificates from an end 
entity to a top level certification authority. The constructed certificate group format (such as ordering) is 
implementation specific. However, the subject or end-entity is always the first certificate in the group. 


A partially constructed certificate group is specified in CertGroupFrag. The first certificate is interpreted to 
be the subject or end-entity certificate. Subsequent certificates in the CertGroupFrag structure may be used 
during the construction of a certificate group in conjunction with certificates found in the data stores specified 
in DBList. The trust policy defines the certificates that will be included in the resulting set. 


The output set is a sequence of certificates ordered by the relationship among them. The result set can be 
augmented by adding semantically-related certificates obtained by searching the certificate data stores 
specified in DBList. The data stores are searched in order of appearance in DBList. If the TP supports a 
hierarchical model of certificates, the function output is an uninterrupted, ordered chain of certificates based 
on the first certificate as the leaf of the certificate chain. If the certificate is multiply-signed, then the ordered 
chain will follow the first signing certificate. The function should also detect cross-certificate pairs and should 
include both certificates without duplicating either certificate. 


E xtraneous certificates in the CertGroupFrag fragment or contained in the DBList data stores are ignored. 
The certificate group returned by this function can be used as input to the function 
CSSM_TP_CertGroupVerify() (CSSM API), or TP_CertGroupVerify() (TP SPI). 


The constructed certificate group can be consistent locally or globally. Consistency can be limited to the local 
system if locally-defined points of trust are inserted into the group. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 
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CSSMERR_TP_INVALID_CL_HANDLE 
CSSMERR_TP_INVALID_CSP_HANDLE 
CSSMERR_TP_INVALTID_DL_HANDLE 
CSSMERR_TP_INVALID_DB HANDLE 
CSSMERR_TP_INVALID_DB_ LIST _POINTER 
CSSMERR_TP_INVALID DB LIST 
CSSMERR_TP_INVALID_CERTGROUP_POINTER 
CSSMERR_TP_INVALID_CERTGROUP 
CSSMERR_TP_INVALID_ CERTIFICATE 
CSSMERR_TP_CERTGROUP_INCOMPLETE 
SEE ALSO 

Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 
CSSM_TP_CetGroupPrune CSSM_TP_CertGroupVerify 
Functions for the TP SPI: 

TP_CertGroupPrune, TP_CertGroupVerify 
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TP_CertGroupPrune 
NAME 


TP_CertGroupPrune: CSSM_TP_CertGroupPrune - Remove locally issued anchor certificates 
(CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_TP_CertGroupPrune 
(CSSM_TP_HANDLE TPHandle, 

CSSM_CL_HANDLE CLHandle, 

const CSSM_DL_DB LIST *DBList, 

const CSSM_CERTGROUP *OrderedCertGroup, 


CSSM_CERTGROUP_PTR *PrunedCertGroup) 


CSSM_RETURN CSSMTPI TP_CertGroupPrune 
(CSSM_TP_HANDLE TPHandle, 
CSSM_CL_HANDLE CLHandle, 

const CSSM_DL_DB_LIST *DBList, 

const CSSM_CERTGROUP *OrderedCertGroup, 


CSSM_CERTGROUP_PTR *PrunedCertGroup) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


TPHandle (input) 


The handle to the trust policy module to perform this operation. 


CLHand1le (input/optional) 


The handle to the certificate library module that can be used to manipulate and parse the 
certgroup certificates and the certificates in the specified data stores. I f no certificate library 
module is specified, the TP module uses an assumed CL module. 


DBList (input) 


A list of handle pairs specifying a data storage library module and a data store, identifying 
certificate databases containing certificates (and possibly other security objects) that are 
managed by that module. The data stores are searched for anchor certificates restricted to 
have local scope. These certificates are candidates for removal from the subject certificate 


group. 
OrderedCertGroup (input) 


The initial complete set of semantically-related certificates - for example, the result of a 
CSSM_TP_CertGroupConstruct () (CSSM API), or TP_CertGroupConstruct () (TP SPI), 
call - from which certificates will be selectively removed. 


PrunedCertGroup (output) 
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A pointer toa certificate group containing those certificates which are verifiable credentials 
outside of the local system. The CSSM_CERTGROUP and its substructure is allocated by 
the service provider and must be deallocated by the application. 


DESCRIPTION 


This function removes any locally issued anchor certificates from a constructed certificate group. The prune 
operation can remove those certificates that have been signed by any local certificate authority, as it is 
possible that these certificates will not be meaningful on other systems. 


This operation can also remove additional certificates that can be added to the certificate group again using 
the CSSM_TP_CertGroupConstruct () (CSSM API), or TP_CertGroupConstruct () (TP SPI), operation. The 
pruned certificate group should be suitable for export to external hosts/entities, which can in turn reconstruct 
and verify the certificate group. 


The DBList parameter specifies a set of data stores containing certificates that should be pruned from the 
group. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 

Errors are described in the CDSA Technical Standard. 
CSSMERR_TP_INVALID_CL_HANDLE 
CSSMERR_TP_INVALTID_DL_HANDLE 
CSSMERR_TP_INVALID_DB HANDLE 
CSSMERR_TP_INVALID_ DB LIST POINTER 
CSSMERR_TP_INVALID_DB_ LIST 
CSSMERR_TP_INVALID_CERTGROUP_POINTER 
CSSMERR_TP_INVALID_CERTGROUP 
CSSMERR_TP_INVALID_ CERTIFICATE 
CSSMERR_TP_CERTGROUP_INCOMPLETE 
SEE ALSO 

Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 
CSSM_TP_CertGroupConstruct, CSSM_TP_CertGroupVerify 
Functions for the TP SPI: 

TP_CertGroupConstruct, TP_CertGroupVerify 
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TP_CertGroupToTupleGroup 
NAME 


TP_CertGroupToTupleGroup: CSSM_TP_CertGroupToT upleGroup - Create a set of authorization 
tuples (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 
CSSM_RETURN CSSMAPI CSSM_TP_CertGroupToTupleGroup 
(CSSM_TP_HANDLE TPHandle, 


CSSM_CL_HANDLE CLHandle, 

const CSSM_CERTGROUP *CertGroup, 
CSSM_TUPLEGROUP_PTR *TupleGroup) 
BPI¢ 
CSSM_RETURN CSSMTPI TP_CertGroupToTupleGroup 
(CSSM_TP_HANDLE TPHandle, 

CSSM_CL_HANDLE CLHandle, 

const CSSM_CERTGROUP *CertGroup, 
CSSM_TUPLEGROUP_PTR *TupleGroup) 


LIBRARY 


Common Security Services Manager library (cdsa$Sincssm300_shr.exe) 


PARAMETERS 


TPHandle (input) 


The handle that describes the trust policy service module used to perform this function. 


CLHand1le (input/optional) 


The handle that describes the certificate library module that can be used to scan the 
certificate fields for values. If no certificate library module is specified, the TP module uses 
an assumed CL module. 


CertGroup (input) 


A group of certificates in the native certificate format supported by the Trust Policy module. 
The certificates carry authorizations for one or more certificate subjects. 


TupleGroup (output) 


A pointer to a structure containing references to one or more tuples resulting from the 
translation process. Storage for structure and the tuples is allocated by the service provider 
and must be deallocated by the application. 


DESCRIPTION 


This function creates a set of authorization tuples based on a set of input certificates. The certificates must be 
of the type managed by the Trust Policy module. The trust policy module may require that the input 
certificates be successfully verified before being translated to tuples. It is assumed that the certificates carry 
authorizations. The trust policy service provider interprets the certificate authorization fields and generates 
one or more tuples corresponding to those authorizations. The certificates of the type managed by the Trust 
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Policy module. The resulting tuples can be input to an authorization evaluation function, such as 
CSSM_AC_AuthCompute() (CSSM API), or AC_AuthCompute () (AC SPI), which determines whether a 
particular action is authorized under a basic set of authorization assumptions. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_TP_INVALID_CL_HANDLE 
CSSMERR_TP_INVALID_CERTGROUP_POINTER 
CSSMERR_TP_INVALID_CERTGROUP 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 
CSSM_TP_TupleGroupToCertGroup, CSSM_AC AuthCompute 
Functions for the TP SPI: 

TP_TupleGroupToCertGroup, AC_AuthCompute 
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TP_CertGroupVerify 


NAME 
TP_CertGroupVerify: CSSM_TP_CertGroupVerify - Determine if a certificate is trusted (CDSA) 


SYNOPSIS 


# include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_TP_CertGroupVerify 
(CSSM_TP_HANDLE TPHandle, 

CSSM_CL_HANDLE CLHandle, 

CSSM_CSP_HANDLE CSPHandle, 

const CSSM_CERTGROUP *CertGroupToBeVerified, 

const CSSM_TP_VERIFY_CONTEXT *VerifyContext, 
CSSM_TP_VERIFY_CONTEXT_RESULT_PTR VerifyContextResult) 
SPI: 
CSSM_RETURN CSSMTPI TP_CertGroupVerify 

(CSSM_TP_HANDLE TPHandle, 

CSSM_CL_HANDLE CLHandle, 

CSSM_CSP_HANDLE CSPHandle, 

const CSSM_CERTGROUP *CertGroupToBeVerified, 

const CSSM_TP_VERIFY_CONTEXT *VerifyContext, 
CSSM_TP_VERIFY_CONTEXT_RESULT_PTR VerifyContextResult) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


TPHandle (input) 


The handle that describes the add-in trust policy module used to perform this function. 


CLHand1le (input/optional) 


The handle that describes the add-in certificate library module that can be used to 
manipulate the subject certificate and anchor certificates. If no certificate library module is 
specified, the TP module uses an assumed CL module, if required. 


CSPHand1le (input/optional) 


The handle that describes the add-in Cryptographic Service Provider module that can be 
used to perform the cryptographic operations required to carry out the verification. If no 
CSP handle is specified, the TP module allocates a suitable CSP. 


CertGroupToBeVerified (input) 


A group of one or more certificates to be verified. The first certificate in the group is the 
primary target certificate for verification. Use of the subsequent certificates during the 
verification process is specific to the trust domain. 


VerifyContext (input/optional) 
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A structure containing credentials, policy information, and contextual information to be 
used in the verification process. All of the input values in the context are optional except 
Action. The service provider can define default values or can attempt to operate without 
input for all the other fields of this input structure. The operation can fail if a necessary 
input value is omitted and the service module can not define an appropriate default value. 


VerifyContextResult (output/optional) 


A pointer to a structure containing information generated during the verification process. 
The information can include: 


Evidence (output/optional ) 


NumberOfEvidences (output/optional ) 


DESCRIPTION 


This function determines whether the certificate is trusted. The actions performed by this function differ 
based on the trust policy domain. The factors include practices, procedures and policies defined by the 
certificate issuer. 


Typically certificate verification involves the verification of multiple certificates. The first certificate in the 
group is the target of the verification process. The other certificates in the group are used in the verification 
process to connect the target certificate with one or more anchors of trust. The supporting certificates can be 
contained in the provided certificate group or can be stored in the data stores specified in the VerifyContext 
DBList. This allows the trust policy module to construct a certificate group and perform verification in one 
operation. The data stores specified by DBList can also contain certificate revocation lists used in the 
verification process. It is also possible to provide a data store of anchor certificates. Typically the points of 
Trust are few in number and are embedded in the caller or in the TPM during software manufacturing or at 
runtime 


The caller can select to be notified incrementally as each certificate is verified. The 
CallbackWithVerifiedCert parameter (in the verifyContext) can specify a caller function to be invoked at 
the end of each certificate verification, returning the verified certificate for use by the caller. 


Anchor certificates area list of implicitly trusted certificates. These include root certificates, cross certified 
certificates, and locally defined sources of trust. These certificates form the basis to determine trust in the 
subject certificate. 


A policy identifier can specify an additional set of conditions that must be satisfied by the subject certificate 
in order to meet the trust criteria. The name space for policy identifiers is defined by the application domains 
to which the policy applies. This is outside of CSSM. A list of policy identifiers can be specified and the 
stopping condition for evaluating that set of conditions. 


The evaluation and verification process can produce a list of evidence. The evidence can be selected values 
from the certificates examined in the verification process, entire certificates from the process or other 
pertinent information that forms an audit trail of the verification process. This evidence is returned to the 
caller after all steps in the verification process have been completed. 


If verification succeeds, the trust policy module may carry out the action on the specified data or may return 
approval for the action requiring the caller to perform the action. The caller must consult TP module 
documentation outside of this specification to determine all module-specific side effects of this operation. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 
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ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_TP_INVALID_CL_HANDLE 
CSSMERR_TP_INVALID_CSP_HANDLE 
CSSMERR_TP_INVALID_CERTGROUP_POINTER 
CSSMERR_TP_INVALID_CERTGROUP 
CSSMERR_TP_INVALID_ CERTIFICATE 
CSSMERR_TP_INVALID_ ACTION 
CSSMERR_TP_INVALID_ACTION_DATA 
CSSMERR_TP_VERIFY_ACTION_FATLED 
CSSMERR_TP_INVALID_CRLGROUP_POINTER 
CSSMERR_TP_INVALID_CRLGROUP 
CSSMERR_TP_INVALID_CRL_ AUTHORITY 
CSSMERR_TP_INVALTID_CALLERAUTH_ CONTEXT POINTER 
CSSMERR_TP_INVALID_POLICY_IDENTIFIERS 
CSSMERR_TP_INVALID_TIMESTRING 
CSSMERR_TP_INVALID_STOP_ON_POLICY 
CSSMERR_TP_INVALID_ CALLBACK 
CSSMERR_TP_INVALID_ANCHOR_CER' 
CSSMERR_TP_CERTGROUP_INCOMPLETE 
CSSMERR_TP_INVALID_DL_ HANDLE 
CSSMERR_TP_INVALID_DB HANDLE 
CSSMERR_TP_INVALID_ DB LIST POINTER 
CSSMERR_TP_INVALID_DB_ LIST 
CSSMERR_TP_AUTHENTICATION_FAILED 
CSSMERR_TP_INSUFFICIENT CREDENTIALS 
CSSMERR_TP_NOT_TRUSTED 
CSSMERR_TP_CERT_REVOKED 
CSSMERR_TP_CERT_SUSPENDED 
CSSMERR_TP_CERT_EXP TIRED 
CSSMERR_TP_CERT_NOT_VALID_YET 
CSSMERR_TP_INVALID_CERT_AUTHORITY 
CSSMERR_TP_INVALID SIGNATURE 
CSSMERR_TP_INVALID_NAMF 

SEE ALSO 

Books 


Inta CDSA Application Devdoper's Guide 
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TP_CertReclaimAbort 
NAME 


TP_CertReclaimAbort: CSSM_TP_CertReclaimAbort - Terminate the process of reclaiming 
certificates (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_TP_CertReclaimAbort 
(CSSM_TP_HANDLE TPHandle, 

CSSM_LONG_HANDLE KeyCacheHandle) 

SPI: 

CSSM_RETURN CSSMTPI TP_CertReclaimAbort 
(CSSM_TP_HANDLE PHandle, 

CSSM_LONG_HANDLE KeyCacheHandle) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 
TPHandle (input) 
The handle that describes the service provider module used to perform this function. 


KeyCacheHandle (input) 


An opaque handle that identifies the cache of protected private keys reclaimed froma 
certificate authority for potentially recovery on the local system. 


DESCRIPTION 


This function terminates the iterative process of reclaiming certificates and recovering their associated 
private keys from a protected key cache. This function must be called even if all private keys are recovered 
from the cache. This function destroys all intermediate state and secret information used during the 
reclamation process. At completion of this function, the cache handle is invalid. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_TP_INVALID_KEYCACHE_HANDLE 
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SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 
CSSM_TP_CertReclaimKey 
Functions for the TP SPI: 
TP_CertReclaimKey 
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TP_CertReclaimKey 


NAME 


TP_CertReclaimK ey: CSSM_TP_CertReclaimKey - Get private key associated with a certificate 
(CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_TP_CertReclaimKey 
(CSSM_TP_HANDLE TPHandle, 

const CSSM_CERTGROUP *CertGroup, 

uint32 CertIndex, 

CSSM_LONG_HANDLE KeyCacheHandle, 

CSSM_CSP_HANDLE CSPHandle, 

const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry) 
SPI: 
CSSM_RETURN CSSMTPI TP_CertReclaimKey 

(CSSM_TP_HANDLE TPHandle, 

const CSSM_CERTGROUP *CertGroup, 

uint32 CertIndex, 

CSSM_LONG_HANDLE KeyCacheHandle, 

CSSM_CSP_HANDLE CSPHandle, 

const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


TPHandle (input) 
The handle that describes the service provider module used to perform this operation. 
CertGroup (input) 


A pointer to a structure containing a reference to a group of certificates and the number of 
certificates contained in that group. The certificate group contains all certificates that are 
candidates for reclamation. 


Cert Index (input) 


An index value that identifies the certificate whose associated private key is to be recovered 
and stored in the local CSP. This index value | references the I-th certificate in CertGroup. 


KeyCacheHandle (input) 


A reference handle that uniquely identifies the cache of protected private keys associated 
with the reclaimed certificates contained in certGroup. The structure of the cache is opaque 
to the caller. 


CSPHandle (input) 
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The handle that describes the CSP module where the private key is to be stored. Optionally, 
the CA service provider can use this CSP to perform additional cryptographic operations or 
may use another default CSP for that purpose. 


CredAndAclEntry (input/optional) 


A structure containing one or more credentials authorized for creating a key and the 
prototype ACL entry that will control future use of the newly created key. The credentials 
and ACL entry prototype can be presented as immediate values or callback functions can be 
provided for use by the CSP to acquire the credentials and/or the ACL entry interactively. | f 
the CSP provides public access for creating a key, then the credentials can be NULL. If the 
CSP defines a default initial ACL entry for the new key, then the ACL entry prototype can 
be an empty list. 


DESCRIPTION 


This function recovers the private key associated with a certificate and securely stores that key in the 
specified Cryptographic Service Provider. The key and its associated certificate are among a set of certificates 
and private keys reclaimed from a certificate authority. 


The particular private key to be recovered to the local system is identified by its associated certificate The 
certificate is identified by its Cert Index position within the cert Group. 


The redamation process associates the private key with the public key contained in the certificate, and 
securely stores the private key in the specified Cryptographic Service Provider. The CSP can require that the 
caller provide access credentials authorizing inserting a new Key into the CSP through an UnwrapKey 
operation. The caller should also provide an initial Access Control List (ACL) entry for the newly inserted key. 
TheACL entry is used to control future use of the recovered private key. These inputs are provided in 
CredAndAclEntry. 


When all required private keys have been reclaimed, the key cache can be discarded using the function 
CSSM_TP_CertReclaimAbort () (CSSM API), or TP_CertReclaimAbort () (TP SPI). The caller must free the 
CertGroup when it is no longer needed. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 

Errors are described in the CDSA Technical Standard. 
CSSMERR_TP_INVALID_CERTGROUP_POINTER 
CSSMERR_TP_INVALTID_CERTGROUP 

CSSMERR_TP_INVALID_ CERTIFICATE 
CSSMERR_TP_INVALID_INDEX 
CSSMERR_TP_INVALID_KEYCACHE HANDLE 
CSSMERR_TP_INVALID_CSP_HANDLE 
CSSMERR_TP_AUTHENTICATION_FAILED 
CSSMERR_TP_INSUFFICIENT_ CREDENTIALS 
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SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 

CSSM_TP_RetrieveCredResult, CSSM_TP_Cert ReclaimAbort 
Functions for the TP SPI: 

TP_RetrieveCredResult, TP_Cert_ReclaimAbort 
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TP_CertRemoveF romCr!ITemplate 
NAME 


TP_CertRemoveF romCrITemplate: CSSM_TP_CertRemoveF romCrITemplate - Determine if the 
revoking certificate group can remove the subject certificate group from the CRL template (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_TP_CertRemoveFromCrlTemplate 
(CSSM_TP_HANDLE TPHandle, 

CSSM_CL_HANDLE CLHandle, 

CSSM_CSP_HANDLE CSPHandle, 

const CSSM_DATA *OldCrlTemplate, 

const CSSM_CERTGROUP *CertGroupToBeRemoved, 

const CSSM_CERTGROUP *RevokerCertGroup, 

const CSSM VERIFY_CONTEXT *RevokerVerifyContext, 
CSSM_TP_VERIFY_CONTEXT_RESULT_PTR RevokerVerifyResult, 
CSSM_DATA_PTR NewCrlTemplate) 

SPI: 
CSSM_RETURN CSSMTPI TP_CertRemoveFromCrlTemplate 
(CSSM_TP_HANDLE TPHandle, 

CSSM_CL_HANDLE CLHandle, 

CSSM_CSP_HANDLE CSPHandle, 

const CSSM_DATA *OldCrlTemplate, 

const CSSM_CERTGROUP *CertGroupToBeRemoved, 

const CSSM_CERTGROUP *RevokerCertGroup, 

const CSSM_TP_VERIFY_CONTEXT *RevokerVerifyContext, 
CSSM_TP_VERIFY_CONTEXT_RESULT_PTR RevokerVerifyResult, 
CSSM_DATA_PTR NewCrlTemplate) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


TPHandle (input) 


The handle that describes the add-in trust policy module used to perform this function. 


CLHand1le (input/optional) 


The handle that describes the add-in certificate library module used to perform this 
function. 


CSPHand1le (input/optional) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform this function. 


OldcrlTemplate (input/optional) 


A pointer to the CSSM_DATA structure containing an existing certificate revocation list. If 
this input is NULL, a new list is created or the operation fails. 
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CertGroupToBeRemoved (input) 
A group of one or more certificates to be removed from the the CRL template. 
RevokerCertGroup (input) 


A group of one or more certificates that partially or fully represent the revoking entity for 
this operation. The first certificate in the group is the target certificate representing the 
revoker. The use of subsequent certificates is specific to the trust domain. 


RevokerVerifyContext (input) 


A structure containing policy elements useful in verifying certificates and their use with 
respect toa security policy. Optional elements in the verify context left unspecified will 
cause the internal default values to be used. Default values are specified in the TP module 
vendor release documents. This context is used to verify the revoker certificate group. 


RevokerVerifyResult (output/optional) 


A pointer to a structure containing information generated during the verification process. 
The information can include: 


Evidence (output/opti onal) 


NumberOfEvidences (output/optional) 


NewCrlTemplate (output) 


A pointer tothe CSSM_DATA structure containing the updated certificate revocation list. If 
the pointer is NULL, an error has occurred. 


DESCRIPTION 


The TP module determines whether the revoking certificate group can remove the subject certificate group 
from the CRL template. The revoker certificate group is first authenticated and its applicability to perform 
this operation is determined. Once the trust is established, the TP removes the certificates from the CRL 
template. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 

Errors are described in the CDSA Technical Standard. 
CSSMERR_TP_INVALID_CL_HANDLE 
CSSMERR_TP_INVALID_CSP_HANDLE 
CSSMERR_TP_INVALID_CRL_ POINTER 
CSSMERR_TP_INVALID_CR 
CSSMERR_TP_UNKNOWN_FORMAT 
CSSMERR_TP_CRL_ALREADY_SIGNED 
CSSMERR_TP_INVALID_CERTGROUP_POINTER 
CSSMERR_TP_INVALTID_CERTGROUP 
CSSMERR_TP_INVALID_ CERTIFICATE 
CSSMERR_TP_INVALID_ ACTION 
CSSMERR_TP_INVALID_ACTION_DATA 
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CSSMERR_TP_VERIFY_ACTION_FAILED 
CSSMERR_TP_INVALID_CRLGROUP_POINTER 
CSSMERR_TP_INVALID_CRLGROUP 
CSSMERR_TP_INVALID_CRL_AUTHORITY 
CSSMERR_TP_IN D_CALLERAUTH_CONTEXT_POINT! 
CSSMERR_TP_IN D_POLICY_IDENTIFIERS 
CSSMERR_TP_IN D_TIMESTRING 
CSSMERR_TP_I D_STOP_ON_POLICY 
CSSMERR_TP_IN D_CALLBACK 
CSSMERR_TP_I D_ANCHOR_CERT 
CSSMERR_TP_CI GROUP_INCOMPLETE 
CSSMERR_TP_I D_DL_HANDLI 
CSSMERR_TP_I D_DB_HANDLE 
CSSMERR_TP_I D_DB_LIST_POINTER 
CSSMERR_TP_I 1sID_DB_LIST 
CSSMERR_TP_A ENTICATION_FAILED 
CSSMERR_TP_I ICIENT_CREDENTIALS 
CSSMERR_TP_N' RUSTED 

CSSMERR_TP_CI REVOKED 
CSSMERR_TP_CI SUSPENDED 
CSSMERR_TP_CI EXPIRED 
CSSMERR_TP_CI NOT_VALID_YET 
CSSMERR_TP_IN 1ID_CERT_AUTHORITY 
CSSMERR_TP_INVALID_SIGNATUR 
CSSMERR_TP_INVALID_NAME 
CSSMERR_TP_CERTIFICATE_CANT_OPERATE 
SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 


Functions for the CSSM API: 
CSSM_CL_CrlAddCet 
Functions for the TP SPI: 


CL_CrlAddCet 


442 


E 


TP_C 
NAM 


ertRevoke 
E 


TP_CertRevoke: CSSM_TP_CertRevoke - Determine if the revoking certificate group can revokethe 
subject certificate group (CDSA) 


SYNOPSIS 


#includ 


APT: 


e <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_TP_CertRevoke 
(CSSM_TP_HANDLE TPHandle, 


CSSM_CL 


HANDLE CLHandle, 


CSSM_CSP_HANDLE CSPHandle, 

const CSSM_DATA *OldCrlTemplate, 

const CSSM_CERTGROUP *CertGroupToBeRevoked, 

const CSSM_CERTGROUP *RevokerCertGroup, 

const CSSM_TP_VERIFY_CONTEXT *RevokerVerifyContext, 


CSS P_VERIFY_CONTEXT_RESULT_PTR RevokerVerifyResult, 


CSSM_TP_CERTCHANGE_REASON Reason, 


CSSM_DATA_PTR NewCrlTemplate) 


SPIs 


CSSM_RETURN CSSMTPI TP_CertRevoke 
(CSSM_TP_HANDLE TPHandle, 


CSSM_CL_ 


HANDLE CLHandle, 


CSSM_CSP_HANDLE CSPHandle, 
const CSSM_DATA *OldCrlTemplate, 


const CSSM_C 
const CSSM_C 
const CSSM 


RTGROUP *CertGroupToBeRevoked, 
RTGROUP *RevokerCertGroup, 
VERIFY_CONTEXT *RevokerVerifyContext, 


CSSM_TP_VERIFY_CONTEXT_RESULT_PTR RevokerVerifyResult, 


CSSM_TP_CERTCHANGE_REASON Reason, 


CSSM_DATA_PTR NewCrlTemplate) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


TPHand]l 


CLHand]l 


le (input) 
The handle that describes the add-in trust policy module used to perform this function. 
le (input/optional) 


The handle that describes the add-in certificate library module used to perform this 
function. 


CSPHand1le (input/optional) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform this function. 


OldcrlTemplate (input/optional) 
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A pointer tothe CSSM_DATA structure containing an existing certificate revocation list. If 
this input is NULL, a new list is created or the operation fails. 


CertGroupToBeRevoked (input) 


A group of one or more certificates that partially or fully represent the certificate to be 
revoked by this operation. The first certificate in the group is the target certificate The use 
of subsequent certificates is specific to the trust domain. For example, in a hierarchical trust 
model subsequent members are intermediate certificates of a certificate chain. 


RevokerCertGroup (input) 


A group of oneor more certificates that partially or fully represent the revoking entity for 
this operation. The first certificate in the group is the target certificate representing the 
revoker. The use of subsequent certificates is specific to the trust domain. 


RevokerVerifyContext (input) 


A structure containing policy elements useful in verifying certificates and their use with 
respect to a security policy. Optional elements in the verify context left unspecified will 
cause the internal default values to be used. Default values are specified in the TP module 
vendor release documents. This context is used to verify the revoker certificate group. 


RevokerVerifyResult (output/optional) 


A pointer toa structure containing information generated during the verification process. 
The information can include: 


Evidence (output/optional) 


NumberOfEvidences (output/optional) 


Reason (input/optional) 
The reason for revoking the subject certificate. 
NewCr1lTemplate (output/optional) 


A pointer tothe CSSM_DATA structure containing the updated certificate revocation list. If 
the pointer is NULL, an error has occurred. 


DESCRIPTION 


The TP module determines whether the revoking certificate group can revoke the subject certificate group. 
The revoker certificate group is first authenticated and its applicability to perform this operation is 
determined. Once the trust is established, the TP revokes the subject certificate by adding it to the certificate 
revocation list. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 
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CSSMERR_TP_INVALID_CL_HANDLE 
CSSMERR_TP_INVALID_CSP_HANDLE 
CSSMERR_TP_INVALID_CRL_POINTER 
CSSMERR_TP_INVALID_CRL 
CSSMERR_TP_UNKNOWN_FORMAT 
CSSMERR_TP_CRL_ALREADY_SIGNED 
CSSMERR_TP_INVALID_CERTGROUP_POINTER 
CSSMERR_TP_INVALID_CERTGROUP 
CSSMERR_TP_INVALID_CERTIFICATE 
CSSMERR_TP_INVALID_ACTION 
CSSMERR_TP_INVALID_ACTION_DATA 
CSSMERR_TP_VERIFY_ACTION_FAILED 
CSSMERR_TP_INVALID_CRLGROUP_POINTER 
CSSMERR_TP_INVALID_CRLGROUP 
CSSMERR_TP_INVALID_CRL_AUTHORITY 
CSSMERR_TP_INVALID_CALLERAUTH_CONTEXT_POINTER 
CSSMERR_TP_INVALID_POLICY_IDENTIFIERS 
CSSMERR_TP_INVALID_TIMESTRING 
CSSMERR_TP_INVALID_STOP_ON_POLICY 
CSSMERR_TP_INVALID_CALLBACK 
CSSMERR_TP_INVALID_ANCHOR_CERT 
CSSMERR_TP_CERTGROUP_INCOMPLETE 
CSSMERR_TP_INVALID_DL_HANDLE 
CSSMERR_TP_INVALID_DB_HANDLE 
CSSMERR_TP_INVALID_DB_LIST_POINTER 
CSSMERR_TP_INVALID_DB_LIST 
CSSMERR_TP_AUTHENTICATION_FAILED 
CSSMERR_TP_INSUFFICIENT_CREDENTIALS 
CSSMERR_TP_NOT_TRUSTED 
CSSMERR_TP_CERT_REVOKED 
CSSMERR_TP_CERT_SUSPENDED 
CSSMERR_TP_CERT_EXPIRED 
CSSMERR_TP_CERT_NOT_VALID_YET 
CSSMERR_TP_INVALID_CERT_AUTHORITY 
CSSMERR_TP_INVALID_SIGNATURE 
CSSMERR_TP_INVALID_NAME 
CSSMERR_TP_CERTIFICATE_CANT_OPERATE 
CSSMERR_TP_INVALID_REASON 

SEE ALSO 


Books 


Inte CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 
CSSM_CL_CrlAddCet 
Functions for the TP SPI: 
CL_CrlAddCet 
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TP_CertSign 


NAME 
TP_CertSign: CSSM_TP_CertSign - Determine if signer certificate is trusted (CDSA) 


SYNOPSIS 


#include <cssm.h> 


APTI: 

CSSM_RETURN CSSMAPI CSSM_TP_CertSign 
(CSSM_TP_HANDLE TPHandle, 

CSSM_CL_HANDLE CLHandle, 

CSSM_CC_HANDLE CCHandle, 

const CSSM_DATA *CertTemplateToBeSigned, 

const CSSM_CERTGROUP *SignerCertGroup, 

const CSSM_TP_VERIFY_CONTEXT *SignerVerifyContext, 


CSSM_TP_VERIFY_CONTEXT_RESULT_PTR SignerVerifyResult, 
CSSM_DATA_PTR SignedCert) 

SPI: 
CSSM_RETURN CSSMTPI TP_CertSign 
(CSSM_TP_HANDLE TPHandle, 

CSSM_CL_HANDLE CLHandle, 

CSSM_CC_HANDLE CCHandle, 

const CSSM_DATA *CertTemplateToBeSigned, 

const CSSM_CERTGROUP *SignerCertGroup, 

const CSSM_TP_VERIFY_CONTEXT *SignerVerifyContext, 
CSSM_TP_VERIFY_CONTEXT_RESULT_PTR SignerVerifyResult, 


CSSM_DATA_PTR SignedCert) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


TPHandle (input) 


The handle that describes the add-in trust policy module used to perform this function. 


CLHand1le (input/optional) 


The handle that describes the add-in certificate library module used to perform this 
function. 


CCHand1le (input/optional) 


The handle that describes the cryptographic context for signing the certificate. This context 
also identifies the Cryptographic Service Provider to be used to perform the signing 
operation. If this handle is not provided by the caller, the trust policy module can assume a 
default signing algorithm and a default CSP. If the trust policy module does not assume 
defaults or the default CSP is not available on the local system, an error occurs. 


CertTemplateToBeSigned (input) 


A pointer toa structure containing a certificte template to be signed. The CRL type and 
encoded are included in this structure. 
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SignerCertGroup (input) 


A group of one or more certificates that partially or fully represent the signer for this 
operation. The first certificate in the group is the target certificate representing the signer. 
Use of subsequent certificates is specific to the trust domain. For example, in a hierarchical 
trust model subsequent members are intermediate certificates of a certificate chain. 


SignerVerifyContext (input/optional) 


A structure containing credentials, policy information, and contextual information to be 
used in the verification process. All of the input values in the context are optional. The 
service provider can define default values or can attempt to operate without input for all the 
other fields of this input structure. The operation can fail if a necessary input value is 
omitted and the service module can not define an appropriate default value. 


SignerVerifyResult (output/optional) 


A pointer to a structure containing information generated during the verification process. 
The information can include: 


Evidence (output/opti onal) 


NumberOfEvidences (output/optional) 


SignedCert (output) 


A pointer tothe CSSM_DATA structure containing the signed certificate. The 
SignedCert->Data is allocated by the service provider and must be deallocated by the 
application. 


DESCRIPTION 


The TP module decides whether the signer certificate is trusted to sign the Cert TemplateToBeSigned. The 
signer certificate group is first authenticated and its applicability to perform this operation is determined. 
Once the trust is established, this operation signs the entire certificate The caller must provide a credential 
that permits the caller to use the private key for this signing operation. The credential can be provided in the 
cryptographic context CCHandle. If CcHandle is NULL, the credentials in the SignerVerifyContext specify 
the credential value. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 

Errors are described in the CDSA Technical Standard. 
CSSMERR_TP_INVALID_CL_HANDLE 
CSSMERR_TP_INVALID_CONTEXT_HANDLE 
CSSMERR_TP_INVALID_CERTGROUP_POINTER 
CSSMERR_TP_INVALTD_CERTGROUP 
CSSMERR_TP_INVALID_ CERTIFICATE 
CSSMERR_TP_UNKNOWN_FORMAT 
CSSMERR_TP_INVALID_ ACTION 
CSSMERR_TP_INVALID_ACTION_DATA 
CSSMERR_TP_VERIFY_ACTION_FATLED 
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CSSMERR_TP_INVALID_CRLGROUP_POINTER 
CSSMERR_TP_INVALTID_CRLGROUP 
CSSMERR_TP_INVALID_CRL_ AUTHORITY 
CSSMERR_TP_INVALID_CALLERAUTH_CONTEXT_POINTI 
CSSMERR_TP_INVALID_POLICY_IDENTIFIERS 
CSSMERR_TP_INVALID_TIMESTRING 
CSSMERR_TP_INVALID_STOP_ON_POLICY 
CSSMERR_TP_INVALID_ CALLBACK 
CSSMERR_TP_INVALID_ANCHOR_CERT 
CSSMERR_TP_CERTGROUP_INCOMPLETE 
CSSMERR_TP_INVALID_DL_HANDLE 
CSSMERR_TP_INVALID_ DB HANDLE 
CSSMERR_TP_INVALID_DB_ LIST POINTER 
CSSMERR_TP_INVALID_DB_ LIST 
CSSMERR_TP_AUTHENTICATION_FAILED 
CSSMERR_TP_INSUFFICIENT_ CREDENTIALS 
CSSMERR_TP_NOT_TRUSTED 
CSSMERR_TP_CERT_REVOKED 
CSSMERR_TP_CERT_SUSPENDED 
CSSMERR_TP_CERT_EXP TIRED 
CSSMERR_TP_CERT_NOT_VALID_YET 
CSSMERR_TP_INVALID_CERT_AUTHORITY 
CSSMERR_TP_INVALID_ SIGNATURE 
CSSMERR_TP_INVALTID_NAMF 
CSSMERR_TP_CERTIFICATE CANT OPERATE 
SEE ALSO 

Books 


Inta CDSA Application Devdoper's Guide 


Online Help 


Functions for the CSSM API: 
CSSM_TP_CetCreatelemplate CSSM_TP_CrlSign 
Functions for the TP SPI: 
TP_CertCreateTemplate, TP_CrlSign 
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TP_ConfirmCredResult 


NAME 
TP_ConfirmCredResult: CSSM_TP_ConfirmCredResult - Confirm credentials (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_TP_ConfirmCredResult 
(CSSM_TP_HANDLE TPHandle, 

const CSSM_DATA *ReferencelIdentifier, 

const CSSM_TP_CALLERAUTH_CONTEXT *CallerAuthCredentials, 
const CSSM_TP_CONFIRM_RESPONSE *Responses, 

const CSSM_TP_AUTHORITY_ID *PreferredAuthority) 

SPL s 
CSSM_RETURN CSSMTPI TP_ConfirmCredResult 
(CSSM_TP_HANDLE TPHandle, 

const CSSM_DATA *ReferencelIdentifier, 
const CSSM_TP_CALLERAUTH_CONTEXT *CallerAuthCredentials, 
const CSSM_TP_CONFIRM_RESPONSE *Responses, 

const CSSM_TP_AUTHORITY_ID *PreferredAuthority) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


TPHandle (input) 


The handle that describes the certification authority module used to perform this function. 


ReferenceIdentifier (input) 


A reference identifier that uniquely identifies execution of the call sequence 
CSSM_TP_SubmitCredRequest () and CSSM_TP_RetrieveCredResult () (or the equivalent 
TP SPI call pair) to submit a set of requests and to retrieve the results of those requests. 


CallerAuthCredentials (input/optional) 


This structure contains a set of caller authentication credentials. The authentication 
information can be a passphrase, a PIN, a completed registration form, a certificate, or a 
template of user-specific data. The required set of credentials is defined by the service 
provider module and recorded in arecord in theMDS Primary relation. Multiple credentials 
can be required. If the local service provider module does not require credentials from a 
caller, then the credentials field of this verification context structure can be NULL. The 
structure optionally contains additional credentials that can be used to support the 
authentication process. Authentication credentials required by the authority should be 
included in the Request Input. The local TP module can forward information from the 
CallerAuthCredentials tothe authority, as appropriate, but is not required to do so. 


Responses (input) 
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An ordered vector of acknowledges indicating the caller's acceptance or rejection of results. 
The vector contains one acknowledgement per result returned by 
CSSM_TP_RetrieveCredResult () (CSSM API), or TP_RetrieveCredResult () (TP SPI). 


PreferredAuthority (input/optional) 


The identifier which uniquely describes the Authority to receive the acknowledgements. 
The structure can include: 


e An identity certificate for the authority 


¢ The location of the authority 


DESCRIPTION 


This function submits a vector of acknowledgements to a Certificate Authority for a set of requests and 
corresponding results identified by ReferenceIdentifier. The caller must execute the call sequence 
CSSM_TP_SubmitCredRequest () and CSSM_TP_RetrieveCredResult () (or the equivalent TP SPI calls) to 
submit a set of requests and to retrieve the results of those requests. Some Certificate Authority services 
accessed through the request and retrieve functions require confirmation. The function 
CSSM_TP_RetrieveCredResult () (CSSM API), or TP_RetrieveCredResult () (TP SPI), returns a value 
indicating whether the caller must invoke CSSM_TP_ConfirmCredResult (), (CSSM API), or 
TP_ConfirmCredResult () (TP SPI), to successfully complete the service. 


The Responses vector accepts or rejects each result independently. If the caller rejects a returned result, the 
action taken by the authority depends on the requested type of service. 


The ReferenceIdentifier also identifies the authority process state associated with the function pair 
CSSM_TP_SubmitCredRequest () and CSSM_TP_RetrieveCredResult () (or the equivalent TP SPI calls). The 
PreferredAuthority information can be used to further identify the authority to receive the 
acknowledgement. After successful execution of this function, the value of the ReferenceIdentifier is 
undefined and should not be used in subsequent operations in the current module attach session. 


This function fails if ReferenceIdentifier is invalid or the Authority process can not be located. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 

Errors are described in the CDSA Technical Standard. 
CSSMERR_TP_INVALID_ IDENTIFIER POINTER 
CSSMERR_TP_INVALID IDENTIFIER 
CSSMERR_TP_INVALID_CALLERAUTH_ CONTEXT POINTER 
CSSMERR_TP_INVALID_POLICY_IDENTIFIERS 
CSSMERR_TP_INVALID_TIMESTRING 
CSSMERR_TP_INVALID_STOP_ON_POLICY 
CSSMERR_TP_INVALID_ CALLBACK 
CSSMERR_TP_INVALID_ANCHOR_CERT 
CSSMERR_TP_CERTGROUP_INCOMPLETE 
CSSMERR_TP_INVALID_DL_HANDLE 
CSSMERR_TP_INVALID_DB HANDLE 
CSSMERR_TP_INVALID_DB_ LIST POINTER 
CSSMERR_TP_INVALID_DB_ LIST 
CSSMERR_TP_AUTHENTICATION_FAILED 
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CSSMERR_TP_INSUFFICIENT CREDENTIALS 
CSSMERR_TP_NOT_TRUSTED 
CSSMERR_TP_CERT_REVOKED 
CSSMERR_TP_CERT_SUSPENDED 
CSSMERR_TP_CERT_EXP TIRED 
CSSMERR_TP_CERT_NOT_VALID_YET 
CSSMERR_TP_INVALID_CERT_AUTHORITY 
CSSMERR_TP_INVALID_ SIGNATURE 
CSSMERR_TP_INVALID_NAMF 
CSSMERR_TP_INVALID_ RESPONSE VECTOR 
CSSMERR_TP_INVALID_ AUTHORITY 
CSSMERR_TP_NO_DEFAULT_ AUTHORITY 
CSSMERR_TP_UNSUPPORTED_ADDR_TYPE 
CSSMERR_TP_INVALID_NETWORK_ADDR 
SEE ALSO 

Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 

CSSM_TP_SubmitCredRequest, CSSM_TP_RetrieveCredResult, CSSM_TP_Rece veConfirmation 
Functions for the TP SPI: 

TP_SubmitCredR equest, TP_RetrieveCredResult, TP_Recei veConfirmation 
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TP_CriCreateTemplate 


NAME 


TP_CriCreatelemplate: CSSM_TP_CrlCreateTemplate - Create an unsigned memory-resident CRL 
template (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 
CSSM_RETURN CSSMAPI CSSM_TP_CrlCreateTemplate 


(CSSM_TP_HANDLE TPHandle, 


CSSM_CL_HANDLE CLHandle, 


uint32 NumberOfFields, 
const CSSM_FIELD *CrlFields, 
CSSM_DATA_PTR NewCrlTemplate) 


CSSM_RETURN CSSMTPI TP_CrlCreateTemplate 
(CSSM_TP_HANDLE TPHandle, 

CSSM_CL_HANDLE CLHandle, 

uint32 NumberOfFields, 

const CSSM_FIELD *CrlFields, 
CSSM_DATA_PTR NewCrlTemplate) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


TPHandle (input) 


The handle that describes the add-in trust policy module used to perform this function. 


CLHand1le (input/optional) 


The handle that describes the add-in certificate library module used to perform this 
function. 


NumberOfFields (input) 
The number of Ol D/value pairs specified in the crl1Fields input parameter. 
CrlFields (input) 


Any array of field OI D/value pairs containing the values to initialize the CRL attribute 
fields 


NewCrlTemplate (output) 


A pointer tothe CSSM_DATA structure containing the new CRL. The NewCr1->Data is 
allocated by the service provider and must be deallocated by the application. 
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DESCRIPTION 


This function creates an unsigned, memory-resident CRL template. Fields in the CRL areinitialized based on 
the descriptive data specified by the OI D/value input pairs in Cr1Fields and the local domain policy of the 
TP. The specified Ol D/value pairs can initialize all or a subset of the general attribute fields in the new CRL, 
though the module developer may specify a set of fields that must be or cannot be set using this operation. 
The NewCrlTemplate output is an unsigned CRL template in the format supported by the TP. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_TP_INVALID_CL_HANDLE 
CSSMERR_TP_INVALID_FIELD_POINTER 
CSSMERR_TP_UNKNOWN_TAG 
CSSMERR_TP_INVALID_NUMBER_OF_FIELDS 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 
CSSM_TP_CrlSignWithKey, CSSM_TP_CrlSignWithCet 
Functions for the TP SPI: 

TP_CrlSignWithKey, TP_CriSignWithCert 
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TP_CrliVerify 


NAME 
TP_CrlVerify: CSSM_TP_CrlVerify - Verify integrity of the certificate revocation list (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_TP_CrlVerify 
(CSSM_TP_HANDLE TPHandle, 

CSSM_CL_HANDLE CLHandle, 

CSSM_CSP_HANDLE CSPHandle, 

const CSSM_ENCODED_CRL *CrlToBeVerified, 


const CSSM_CERTGROUP *SignerCertGroup, 

const CSSM_TP_VERIFY_CONTEXT *VerifyContext, 
CSSM_TP_VERIFY_CONTEXT_RESULT_PTR RevokerVerifyResult) 
SPL 
CSSM_RETURN CSSMTPI TP_CrlVerify 
(CSSM_TP_HANDLE TPHandle, 
CSSM_CL_HANDLE CLHandle, 
CSSM_CSP_HANDLE CSPHandle, 
const CSSM_ENCODED_CRL *CrlToBeVerified, 

const CSSM_CERTGROUP *SignerCertGroup, 

const CSSM_TP_VERIFY_CONTEXT *VerifyContext, 
CSSM_TP_VERIFY_CONTEXT_RESULT_PTR RevokerVerifyResult) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


TPHandle (input) 


The handle that describes the add-in trust policy module used to perform this function. 


CLHand1le (input/optional) 


The handle that describes the add-in certificate library module that can be used to 
manipulate the certificates to be verified. If no certificate library module is specified, the TP 
module uses an assumed CL module, if required. 


CSPHand1le (input/optional) 


The handle referencing a Cryptographic Service Provider to be used to verify signatures on 
the signer's certificate and on the CRL. The TP module is responsible for creating the 
cryptographic context structure required to perform the verification operation. If no CSP is 
specified, the TP module uses an assumed CSP to perform the operations. 


CrlToBeVerified (input) 


A pointer tothe CSSM_DATA structure containing a signed certificate revocation list to be 
verified. The CRL type and encoding are included in this structure. 


SignerCertGroup (input) 
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A pointer tothe CSSM_CERTGROUP structure containing one or more related certificates 
that paretially or fully represent the signer of the certificate revocation list. The first 
certificate in the group is the target certificate representing the CRL signer. Use of 
subsequent certificates is specific to the trust domain. For example, in a hierarchical trust 
model subsequent members are intermediate certificates of a certificate chain - the caller 
can specify additional points of trust represented by anchor certificates in the 
VerifyContext. The trust policy module can use these additional points of trust in the 
verification process. 


VerifyContext (input/optional) 


A structure containing credentials, policy information, and contextual information to be 
used in the verification process. All of the input values in the context are optional. The 
service provider can define default values or can attempt to operate without input for all the 
other fields of this input structure. The operation can fail if a necessary input value is 
omitted and the service module can not define an appropriate default value. 


RevokerVerifyResult (output/optional) 


A pointer to a structure containing information generation during the verification process. 
The information can include: 


Evidence (output/opti onal) 


NumberOfEvidences (output/optional) 


DESCRIPTION 


This function verifies the integrity of the certificate revocation list and determines whether it is trusted. The 
conditions for trust are part of the trust policy module. It can include conditions such as validity of the 
signer's certificate, verification of the signature on the CRL, the identity of the signer, the identity of the 
sender of the CRL, date the CRL was issued, the effective dates on the CRL, and soon. 


The caller can specify additional points of trust represented by anchor certificates in the verifyContext. The 
trust policy module can use these additional points of trust in the verification process. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 

Errors are described in the CDSA Technical Standard. 
CSSMERR_TP_INVALID_CL_HANDLE 
CSSMERR_TP_INVALID_CSP_HANDLE 
CSSMERR_TP_INVALID_CRL_TYPE 
CSSMERR_TP_INVALID_CRL_ENCODING 
CSSMERR_TP_INVALID_CRL_ POINTER 
CSSMERR_TP_INVALID_CRL 
CSSMERR_TP_INVALID_CERTGROUP_POINTER 
CSSMERR_TP_INVALTID_CERTGROUP 
CSSMERR_TP_INVALID_ CERTIFICATE 
CSSMERR_TP_INVALID_ ACTION 
CSSMERR_TP_INVALID_ACTION_DATA 
CSSMERR_TP_VERIFY_ACTION_FATLED 
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CSSMERR_TP_INVALID_CRLGROUP_POINTER 
CSSMERR_TP_INVALTID_CRLGROUP 
CSSMERR_TP_INVALID_CRL_ AUTHORITY 
CSSMERR_TP_INVALID_CALLERAUTH_CONTEXT_POINTI 
CSSMERR_TP_INVALID_POLICY_IDENTIFIERS 
CSSMERR_TP_INVALID_TIMESTRING 
CSSMERR_TP_INVALID_STOP_ON_POLICY 
CSSMERR_TP_INVALID_ CALLBACK 
CSSMERR_TP_INVALID_ANCHOR_CERT 
CSSMERR_TP_CERTGROUP_INCOMPLETE 
CSSMERR_TP_INVALID_DL_HANDLE 
CSSMERR_TP_INVALID_ DB HANDLE 
CSSMERR_TP_INVALID_DB_ LIST POINTER 
CSSMERR_TP_INVALID_DB_ LIST 
CSSMERR_TP_AUTHENTICATION_FAILED 
CSSMERR_TP_INSUFFICIENT_ CREDENTIALS 
CSSMERR_TP_NOT_TRUSTED 
CSSMERR_TP_CERT_REVOKED 
CSSMERR_TP_CERT_SUSPENDED 
CSSMERR_TP_CERT_EXP TIRED 
CSSMERR_TP_CERT_NOT_VALID_YET 
CSSMERR_TP_INVALID_CERT_AUTHORITY 
CSSMERR_TP_INVALID_ SIGNATURE 
CSSMERR_TP_INVALTID_NAMF 
CSSMERR_TP_CERTIFICATE CANT OPERATE 
SEE ALSO 

Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 
CSSM_CL_CrlVerify 
Functions for the TP SPI: 
CL_CrlVerify 
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TP_FormRequest 


NAME 
TP_FormRequest: CSSM_TP_FormRequest - Get form from authority (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_TP_FormRequest 
(CSSM_TP_HANDLE TPHandle, 

const CSSM_TP_AUTHORITY_ID *PreferredAuthority, 
CSSM_TP_FORM_TYPE FormType, 

CSSM_DATA_ PTR BlankForm) 

SPI: 
CSSM_RETURN CSSMTPI TP_FormRequest 
(CSSM_TP_HANDLE TPHandle, 

const CSSM_TP_AUTHORITY_ID *PreferredAuthority, 
CSSM_TP_FORM_TYPE FormType, 

CSSM_DATA_ PTR BlankForm) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


TPHandle (input) 
The handle that describes the certification authority module used to perform this function. 
PreferredAuthority (input/optional) 


A CSSM_TP_AUTHORITY_ID structure containing either a certificate that identifies the 
Authority process, or a network address directly or indirectly identifying the location of the 
authority. If the input is NULL, the module can assume a default authority location. If a 
default authority can not be assumed, the request can not be initiated and the operation 
fails. 


FormType (input) 
Indicates the type of form being requested. 
BlankForm (output) 


A CSSM_DATA structure containing the requested form. The caller must have knowledge of 
the structure of the form based on FormType. 


DESCRIPTION 


This function returns a blank form of type FormType from an Authority. If the PreferredAuthority list is 
NULL, the CA module can use a default authority name and location based on FormType. The CA module 
must incorporate knowledge of the interface protocol for communicating with the authority. 
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ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_TP_INVALID_AUTHORITY 
CSSMERR_TP_NO_DEFAULT_AUTHORITY 
CSSMERR_TP_UNSUPPORTED_ADDR_TYPE 
CSSMERR_TP_INVALID_NETWORK_ADDR 
CSSMERR_TP_INVALID_FORM_TYPE 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 
CSSM_TP_FormSubmit 
Functions for the TP SPI: 
TP_FormSubmit 
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TP_FormSubmit 


NAME 
TP_FormSubmit: CSSM_TP_FormSubmit - Submit form to ClearanceAuthority (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_TP_FormSubmit 
(CSSM_TP_HANDLE TPHandle, 

CSSM_TP_FORM_TYPE FormType, 

const CSSM_DATA *Form, 

const CSSM_TP_AUTHORITY_ID *ClearanceAuthority, 
const CSSM_TP_AUTHORITY_ID *RepresentedAuthority, 


CSSM_ACCESS_CREDENTIALS_PTR Credentials) 
SPI: 
CSSM_RETURN CSSMTPI TP_FormSubmit 

(CSSM_TP_HANDLE TPHandle, 

CSSM_TP_FORM_TYPE FormType, 

const CSSM_DATA *Form, 

const CSSM_TP_AUTHORITY_ID *ClearanceAuthority, 
const CSSM_TP_AUTHORITY_ID *RepresentedAuthority, 
CSSM_ACCESS_CREDENTIALS_PTR Credentials) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


TPHandle (input) 

A handle for the service provider module that will perform the operation. 
FormType (input) 

Indicates the type of form being submitted. 
Form (input) 


A pointer tothe CSSM_DATA structure containing the completed form to be submitted to 
the ClearanceAuthority. 


ClearanceAuthority (input/optional) 


A CSSM_TP_AUTHORITY_ID structure containing either a certificate that identifies the 
clearance authority process, or a network address directly or indirectly identifying the 
location of the authority. If the input is NULL, the service provider module can assume a 
default authority based on the FormType and contents of Form. If a default authority can not 
be assumed, the request can not be initiated and the operation fails. 


RepresentedAuthority (input/optional) 


A CSSM_TP_AUTHORITY_ID structure containing either a certificate that identifies the 
authority represented by the ClearanceAuthority, or a network address directly or 
indirectly identifying the location of the authority. If the input is NULL, the service provider 
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module can assume a default authority based on the FormType and contents of Form. If a 
default authority can not be assumed, the request can not be initiated and the operation 
fails. 


Credentials (output/optional) 


A pointer toa structure containing one or more credentials issued in response to the 
contents of the Form. If the output is NULL, either no credentials were returned or an error 
occurred. 


DESCRIPTION 


The completed Form is submitted to a ClearanceAuthority, who is acting on behalf of a 
RepresentedAuthority. Typically the submitted form is requesting an authorization credential required as 
input to future service requests to the RepresentedAuthority. 


If the form is honored by the ClearanceAuthority, then a set of one or more Credentials is returned tothe 
requester. These credential can be used as the input credential in future service requests submitted to the 
RepresentedAuthority. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 

Errors are described in the CDSA Technical Standard. 
CSSMERR_TP_INVALID_FORM_TYPE 
CSSMERR_TP_INVALID_ AUTHORITY 
CSSMERR_TP_NO_DEFAULT_ AUTHORITY 
CSSMERR_TP_UNSUPPORTED_ADDR_TYPE 
CSSMERR_TP_INVALID_NETWORK_ADDR 
CSSMERR_TP_AUTHENTICATION_FAILED 
CSSMERR_TP_INSUFFICIENT CREDENTIALS 
CSSMERR_TP_REJECTED_FORM 

SEE ALSO 

Books 


Inte CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 
CSSM_TP_FormRequest 
Functions for the TP SPI: 
TP_FormRequest 
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TP_PassThrough 


NAME 
TP_PassThrough: CSSM_TP_PassThrough - Extend trust policy functionality 


SYNOPSIS 


#include <cssm.h> 


APTI: 

CSSM_RETURN CSSMAPI CSSM_TP_PassThrough 
(CSSM_TP_HANDLE TPHandle, 
CSSM_CL_HANDLE CLHandle, 

CSSM_CC_HANDLE CCHandle, 

const CSSM_DL_DB_ LIST *DBList, 

uint32 PassThroughId, 

const void *InputParams, 

void **OutputParams) 


SPL 

CSSM_RETURN CSSMTPI TP_PassThrough 
(CSSM_TP_HANDLE TPHandle, 
CSSM_CL_HANDLE CLHandle, 


CSSM_CC_HANDLE CCHandle, 

const CSSM_DL_DB_ LIST *DBList, 
uint32 PassThroughId, 

const void *InputParams, 

void **OutputParams) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


TPHandle (input) 


The handle that describes the add-in trust policy module used to perform this function. 


CLHand1le (input/optional) 


The handle that describes the add-in certificate library module that can be used to 
manipulate the subject certificate and anchor certificates. If no certificate library module is 
specified, the TP module uses an assumed CL module, if required. 


CCHand1e (input/optional) 


The handle that describes the context of the cryptographic operation. If the modulespecific 
operation does not perform any cryptographic operations, a cryptographic context is not 
required 


DBList (input/optional) 


A list of handle pairs specifying a data storage library module and a data store, identifying 
certificate databases containing certificates (and possibly other security objects) that may 
be used by the pass-through function. If no DL and DB handle pairs are specified, the TP 
module can use an assumed DL module and an assumed data store for this operation. 


PassThroughId (input) 
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An identifier assigned by a TP module to indicate the exported function to be performed. 
InputParams (input/optional) 


A pointer to a module, implementation-specific structure containing parameters to be 
interpreted in a function-specific manner by the requested TP module. 


OutputParams (output/optional) 


A pointer to a module, implementation-specific structure containing the output data. The 
service provider allocates the memory for substructures. The application must free the 
memory for the substructures. 


DESCRIPTION 


This function allows applications to call trust policy module-specific operations that have been exported. Such 
operations may include queries or services specific to the domain represented by the TP module. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_TP_INVALID_CL_HANDLE 
CSSMERR_TP_INVALID_CONTEXT_HANDLE 
CSSMERR_TP_INVALID_DL_HANDLE 
CSSMERR_TP_INVALID_DB_HANDLE 
CSSMERR_TP_INVALID_DB_LIST_POINTER 
CSSMERR_TP_INVALID_DB_LIST 
CSSMERR_TP_INVALID_PASSTHROUGH_ID 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


462 


TP_ReceiveConfirmation 


NAME 
TP_ReceiveConfirmation: CSSM_TP_ReceiveConfirmation - Poll for confirmation (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 
CSSM_RETURN CSSMAPI CSSM_TP_ReceiveConfirmation 
(CSSM_TP_HANDLE TPHandle, 

const CSSM_DATA *ReferencelIdentifier, 
CSSM_TP_CONFIRM_RESPONSE_PTR *Responses, 

sint32 *ElapsedTime) 
SPI: 
CSSM_RETURN CSSMTPI TP_ReceiveConfirmation 
(CSSM_TP_HANDLE TPHandle, 

const CSSM_DATA *ReferenceIdentifier, 
CSSM_TP_CONFIRM_RESPONSE_PTR *Responses, 
sint32 *ElapsedTime) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


TPHandle (input) 


The handle that describes the certification authority module used to perform this function. 


ReferenceIdentifier (input) 


A reference identifier that uniquely identifies a set of service requests and the results 
created in response to those requests. 


Responses (output) 


An ordered vector of acknowledges indicating the caller's acceptance or rejection of results. 
The vector contains one acknowledgement per result created by the certificate authority. 


ElapsedTime (output) 


If the confirmation has not been received, this output value is the number of seconds 
elapsed since the certificate authority created the results or 

CSSM_ELAPSED_TIME_ UNKNOWN. If the confirmation has been received, this output 
value is CSSM_ELAPSED_TIME_COMPLETE. 


DESCRIPTION 


A certificate authority uses this function to poll for confirmation from a requester who has been served by the 
authority. A requester sends a confirmation to the authority by successfully invoking the function 
CSSM_TP_ConfirmCredResult () (CSSM API), or TP_ConfirmCredResult () (TP SPI). 
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The ReferenceIdentifier uniquely identifies the service request and corresponding results for which 
confirmation is expected. This reference identifier need not be identical to the reference identifier used by the 
requester, but a one-to-one mapping between the two name spaces must be well-defined. 


Responses is an ordered vector of acknowledgements indicating, for each returned result, whether the result 
was accepted or rejected by the original requester for whom the service was performed. 


If aresult is rejected by the receiver, then the authority process must undo the service if a reverse operation is 
possible and available. 


If a fatal error occurs, this function returns an error code, indicating that the function call can never be 
completed. If confirmation has not been received, the function return value is CSSM_OK and the 
ElapsedTime is returned to the caller of this function. The time represents elapsed seconds since the service 
results were produced by the authority process. Note that there can be a difference between the time the 
authority process produces the results and the time the results are actually received by the requester. 
Elapsed time is relative and should increase with consecutive calls using the same ReferenceIdentifier. If 
the TP module has no knowledge of the elapsed time, the value CSSM_ELAPSED_TIME_UNKNOWN must 
be returned. I f the service requester has confirmed receipt of the service results, this function returns 
CSSM_OK and ElapsedTime is CSSM_ ELAPSED TIME COMPLETE. 


This function can be invoked repeatedly until the confirmation is received or until the caller decides the 
acknowledgement may be lost and chooses to undo the results of the original service request. 


This function fails if the ReferenceIdentifier is invalid or does not match any requested service for which 
confirmation is expected. 


RETURN VALUE 


A CSSM return value combined with elapsed time to indicate one of three results: 


Complete Function Function Return RetrieveOutput EstimatedTime 
Result Value 
Confirmation Received CSSM_OK CSSM_ELAPSED_TIME_ 
COMPLETE 
Confirmation not received, CSSM_OK CSSM_ELAPSED_TIME_ 
but expected in the future UNKNOWN or <elapsed 
seconds> 
Fatal Error, Confirmation (!1CSSM_OK) NA 
is not expected 


For a return value of ((CSSM_OK), the return value is an error code. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_TP_INVALID_IDENTIFIER_POINTER 
CSSMERR_TP_INVALID_IDENTIFIER 


464 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 
CSSM_TP_ConfirmCredResult 
Functions for the TP SPI: 
CSSM_TP_ConfirmCredResult 
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TP_SubmitCredR equest 
NAME 
TP_SubmitCredRequest: CSSM_TP_SubmitCredRequest - Submit credential request (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_TP_SubmitCredRequest 
(CSSM_TP_HANDLE TPHandle, 

const CSSM_TP_AUTHORITY_ID *PreferredAuthority, 
CSSM_TP_AUTHORITY_REQUEST_TYPE RequestType, 
const CSSM_TP_REQUEST_SET *RequestInput, 

const CSSM_TP_CALLERAUTH_CONTEXT *CallerAuthContext, 
sint32 *EstimatedTime, 

CSSM_DATA_ PTR ReferenceIdentifier) 

SPL 
CSSM_RETURN CSSMTPI TP_SubmitCredRequest 
(CSSM_TP_HANDLE TPHandle, 

const CSSM_TP_AUTHORITY_ID *PreferredAuthority, 


CSSM_TP_AUTHORITY_REQUEST_TYPE RequestType, 
const CSSM_TP_REQUEST_SET *RequestInput, 


const CSSM_TP_CALLERAUTH_CONTEXT *CallerAuthContext, 
sint32 *EstimatedTime, 
CSSM_DATA_PTR ReferencelIdentifier) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


TPHandle (input) 
The handle that describes the certification authority module used to perform this function. 
PreferredAuthority (input/optional) 


The identifier which uniquely describes the Certificate Service Authority to submit the 
request to. 


RequestType (input) 
The identifier of the type of request to submit. 
Request Input (input) 


A pointer to the input parameters to be submitted to the authority who will perform the 
requested service. 


CallerAuthContext (input/optional) 


This structure contains a set of caller authentication credentials. The authentication 
information can be a passphrase, a PIN, a completed registration form, a certificate, or a 
template of user-specific data. The required set of credentials is defined by the service 
provider module and recorded in the MDS Primary relation. Multiple credentials can be 
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required. If the local service provider module does not require credentials from a caller, then 
the CallerCredentials field of this verification context structure can be NULL. The 
structure optionally contains additional credentials that can be used to support the 
authentication process. Authentication credentials required by the authority should be 
included in the Request Input. The local service provider module can forward this 
credential information to the authority, as appropriate, but is not required to do so. 


Est imatedTime (output) 


The number of estimated seconds before the service results are ready to be retrieved. A 
(default) value of zero indicates that the results can be retrieved immediately via the 
corresponding CSSM_TP_RetrieveCredResult () (CSSM API), or 

TP_RetrieveCredResult () (TP SPI), function call. When the local service provider module 
or the authority cannot estimate the time required to perform the requested service, the 
output value for estimated timeis CSSM_ESTIMATED_TIME_UNKNOWN. 


ReferencelIdentifier (output) 


A reference identifier, which uniquely identifies this specific request. The handle persists 
across application executions and becomes undefined when all local processing of the 
request has completed. Local processing is completed in one of two ways: 


¢ For certificate services that do not require explicit confirmation by the requester, the 
reference identifier is invalidated when the corresponding 
CSSM_TP_RetrieveCredResult () (CSSM API), or TP_RetrieveCredResult () (TP 
SPI), function completes (by returning valid results or by failure, which blocks returned 
results) 


¢ For certificate services that require explicit confirmation by the requester, the reference 
identifier is invalidated by successfully invoking the function 
CSSM_TP_ConfirmCredResu() (CSSM API), or CSSM_TP_ConfirmCredResult () (TP 
SPI). 


DESCRIPTION 


If the caller is successfully authenticated, then this function submits a request to the Authority identified by 
PreferredAuthority. The authority service can be local or remote. If the Authority is not specified, then the 
TP module can assume a default authority based on the Request Type and the CallerAuthContext. 
RequestType indicates the type of Authority request and Request Input specifies the input parameters 
needed by the authority to perform the request. 


The request is submitted to the authority only if the TP module can successfully authenticate the caller. The 
CallerAuthContext presents the caller's credentials and a list of one or more policies under which the caller 
should be authenticated. Caller credentials can be presented in several forms: 


« Memory-resident credential values, directly referenced by the structure 
¢ Data bases containing credentials 
¢ Callback functions that can be invoked to obtain credentials from an active entity 


The local service provider must select and forward the credentials required by the Authority. The caller must 
provide all necessary credentials through the callerAuthContext parameter. 


If the caller can not be authenticated by the local service provider, the function fails and the request is not 
submitted to the selected authority. 
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This function returns a ReferenceIdentifier and an EstimatedTime (Specified in seconds). 
ReferenceIdentifier isan ID for the submitted request. Est imatedTime defines the expected time to 
process the request. This time may be substantial when the request requires offline authentication 
procedures by the Authority process. In contrast, the estimated time can be zero, meaning the result can be 
obtained immediately using CSSM_TP_RetrieveCredResult () (CSSM API), or TP_RetrieveCredResult () 
(TP SPI). After the specified time has elapsed, the caller must use the function 
CSSM_TP_RetrieveCredResult () (CSSMAPI), or TP_RetrieveCredResult () (TP SPI), with the reference 
identifier, to obtain the result of the request. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 

Errors are described in the CDSA Technical Standard. 
CSSMERR_TP_INVALID_ AUTHORITY 
CSSMERR_TP_NO_DEFAULT_ AUTHORITY 
CSSMERR_TP_UNSUPPORTED_ADDR_TYPE 
CSSMERR_TP_INVALID_NETWORK_ADDR 
CSSMERR_TP_UNSUPPORTED_SERVICE 
CSSMERR_TP_INVALID_REQUEST_INPUTS 
CSSMERR_TP_INVALID_CALLERAUTH CONTEXT POINTER 
CSSMERR_TP_INVALID_POLICY_IDENTIFIERS 
CSSMERR_TP_INVALID_TIMESTRING 
CSSMERR_TP_INVALID_STOP_ON_POLICY 
CSSMERR_TP_INVALID CALLBACK 
CSSMERR_TP_INVALID_ANCHOR_CER' 
CSSMERR_TP_CERTGROUP_INCOMPLE 
CSSMERR_TP_INVALID_DL_HANDLE 
CSSMERR_TP_INVALTID DB HANDLE 
CSSMERR_TP_INVALID_DB LIST POINTER 
CSSMERR_TP_INVALID_DB_ LIST 
CSSMERR_TP_AUTHENTICATION_FAILED 
CSSMERR_TP_INSUFFICIENT_ CREDENTIALS 
CSSMERR_TP_NOT_TRUSTED 
CSSMERR_TP_CERT_REVOKED 
CSSMERR_TP_CERT SUSPENDED 
CSSMERR_TP_CERT_EXP TIRED 
CSSMERR_TP_CERT_NOT_VALID_YET 
CSSMERR_TP_INVALID_CERT_AUTHORITY 
CSSMERR_TP_INVALID_ SIGNATURE 
CSSMERR_TP_INVALID_NAMEF 

SEE ALSO 

Books 


Inta CDSA Application Devdoper's Guide 


Online Help 
Functions for the CSSM API: 
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CSSM_TP_RetrieveCredResult 
Functions for the TP SPI: 
TP_RetrieveCredResult 
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TP_TupleGroupToCertGroup 
NAME 


TP_TupleGroupToCertGroup: CSSM_TP_TupleGroupToCertGroup - Create a set of certificate 
templates (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_TP_TupleGroupToCertGroup 
(CSSM_TP_HANDLE TPHandle, 

CSSM_CL_HANDLE CLHandle, 


const CSSM_TUPLEGROUP *TupleGroup, 
CSSM_CERTGROUP_PTR *CertTemplates) 


BPI¢ 

CSSM_RETURN CSSMTPI TP_TupleGroupToCertGroup 
(CSSM_TP_HANDLE TPHandle, 

CSSM_CL_HANDLE CLHandle, 


const CSSM_TUPLEGROUP *TupleGroup, 
CSSM_CERTGROUP_PTR *CertTemplates) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


DESCRIPTION 


This function creates a set of certificate templates based on a set of input tuples. The tuples describe a set of 
authorizations for one or more subjects. The trust policy service provider maps these authorizations to 
appropriate template values for one or more certificates of the type managed by the Trust Policy module. The 
resulting certificate templates can be input to a certificate creation function, such as CSSM_CL_CertSign(), 
(CSSM API), or CL_CertSign(), (TP SPI). The signed certificates created by these functions should carry the 
authorizations described in the input tuples. 


PARAMETERS 


TPHandle (input) 


The handle that describes the trust policy service module used to perform this function. 


CLHand1le (input/optional) 


The handle that describes the certificate library module that can be used to assist in the 
creation of field values. If no certificate library module is specified, the TP module uses an 
assumed CL module, if required. 


TupleGroup (input) 
A pointer toa group of CSSM_TUPLE describing authorizations for one or more subjects. 
CertTemplates (output) 


A pointer toa structure containing references to one or more certificate templates resulting 
from the translation process. Storage for the structure and certificate templates is allocated 
by the service provider and must be deallocated by the application. 
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RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 


indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_TP_INVALID_CL_HANDLE 
CSSMERR_TP_INVALID_TUPLEGROUP_POINTER 
CSSMERR_TP_INVALID_TUPLEGROUP 

CSSMERR_TP_INVALID_TUPLE 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

For the CSSM API: 

CSSM_TP_CetGroupToTupleGroup, CSSM_AC AuthCompute 
For the TP SPI: 

TP_CertGroupToTupleGroup, AC_AuthCompute 
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Terminate 
NAME 


Terminate - Clean up module-manager-specific activities (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI Terminate 
(void) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


None. 


DESCRIPTION 


This function performs any module-manager-specific cleanup activities in preparation for unloading of the 
elective module manager. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CSSM_EMM_AUTHENTICATE_FATLED 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 


Functions: Initialize 
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UnwrapKey 


NAME 
UnwrapK ey: CSSM_UnwrapKey, CSP_UnwrapKey - Unwrap the wrapped key (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_UnwrapKey 

(CSSM_CC_HANDLE CCHandle, 

const CSSM_KEY *PublicKey, 

const CSSM_WRAP_KEY *WrappedKey, 

uint32 KeyUsage, 

uint32 KeyAttr, 

const CSSM_DATA *KeyLabel, 

const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry, 
CSSM_KEY_PTR UnwrappedKey, 

CSSM_DATA_PTR DescriptiveData) 

SPIs 
CSSM_RETURN CSSMCSPI CSP_UnwrapKey 
(CSSM_CSP_HANDLE CSPHandle, 
CSSM_CC_HANDLE CCHandle, 

const CSSM_CONTEXT *Context, 

const CSSM_KEY *PublicKey, 

const CSSM_WRAP_KEY *WrappedKey, 
uint32 KeyUsage, 

uint32 KeyAttr, 

const CSSM_DATA *KeyLabel, 

const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry, 
CSSM_KEY_PTR UnwrappedKey, 

CSSM_DATA_PTR DescriptiveData, 

CSSM_PRIVILEGE Privilege) 


LIBRARY 


Common Security Services Manager library (cdsa$Sincssm300_shr.exe) 


API PARAMETERS 


CCHandle (input) 
The handle that describes the context of this cryptographic operation. 
PublicKey (input/optional) 


The public key corresponding to the private key being unwrapped. If a symmetric key is 
being unwrapped, then this parameter must be NULL. 


WrappedKey (input) 


A pointer to the wrapped key. The wrapped key may be a symmetric key or the private key 
of a public/private key pair. The unwrapping method is specified as meta data within the 
wrapped key and is not specified outside of the wrapped key. 


KeyUsage (input) 
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A bit mask indicating all permitted uses for the unwrapped key. If no value is specified, the 
CSP defines the usage mask for the unwrapped key. 


KeyAttr (input) 
A bit mask defining other attribute values to be associated with the unwrapped key. 
KeyLabel (input/optional) 


Pointer to a byte string that will be used as the label for the unwrapped key. 


CredAndAclEntry (input/optional) 


A structure containing one or more credentials authorized for creating a key and the 
prototype ACL entry that will control future use of the newly created key. The credentials 
and ACL entry prototype can be presented as immediate values or callback functions can be 
provided for use by the CSP to acquire the credentials and/or the ACL entry interactively. | f 
the CSP provides public access for creating a key, then the credentials can be NULL. If the 
CSP defines a default initial ACL entry for the new key, then the ACL entry prototype can 
be an empty list. 


UnwrappedKey (output) 
A pointer toa CSSM_KEY structure that returns the unwrapped key. 
DescriptiveData (output) 


A pointer toa CSSM_DATA structure that returns any additional descriptive data that was 
associated with the key during the wrapping operation. It is assumed that the caller 
incorporated knowledge of the structure of this data. | f no additional data is associated with 
the imported key, this output value is NULL. 


SPI PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform up calls to CSSM for the memory functions managed by CSSM. 


CCHandle (input) 

The handle that describes the context of this cryptographic operation. 
Context (input) 

Pointer to CSSM_ CONTEXT structure that describes the attributes with this context. 
Privilege (input) 


The export privilege to be applied during the cryptographic operation. This parameter is 
forwarded to the CSP after CSSM verifies the caller and service provider privilege set 
includes the specified PRIVILEGE. 


DESCRIPTION 


This function unwraps the wrapped key using the context. The wrapped key can be a symmetric key or a 
private key. If the unwrapping algorithm is a symmetric algorithm, then a symmetric context must be 
provided. If the unwrapping algorithm is an asymmetric algorithm, then an asymmetric context must be 
provided. If the key is a private key, then an asymmetric context must be provide describing the unwrapping 
algorithm. The CSP can require the caller to provide credentials authorizing the caller to store the 
unwrapped key within the CSP. The CSP can also require that the caller provide an initial ACL entry to 
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control future access to the newly stored key. These credentials and the initial ACL entry value are provided 
in CredAndAclEntry parameter. If the unwrapping algorithm is CSSM_ALGID_NONE and the wrapped key 
is actually a raw key (as indicated by its key attributes), then the key is imported into the CSP. Support for a 
CSSM_ALGID_NONE unwrapping algorithm is at the option of the CSP. The unwrapped key is restored to 
its original pre-wrap state based on the key attributes recorded by the wrapped key during the wrap 
operation. These attributes must not be modified by the caller. 


Authorization policy can restrict the set of callers who can create a new resource. In this case, the caller must 
present a set of access credentials for authorization. Upon successfully authenticating the credentials, the 
template that verified the presented samples identifies the ACL entry that will be used in the authorization 
computation. If the caller is authorized, the new resource is created. 


The caller must provide an initial ACL entry to be associated with the newly created resource. This entry is 
used to control future access to the new resource and (since the subject is deemed to be the "Owner") exercise 
control over its associated ACL. The caller can specify the following items for initializing an ACL entry: 


e« Subject -A CSSM_LIST structure, containing the type of the subject and a template value that can be 
used to verify samples that are presented in credentials when resource access is requested. 


¢« Delegation flag - A value indicating whether the Subject can delegate the permissions recorded in the 
AuthorizationTag. (This item only applies to public key subjects). 


e Authorization tag - The set of permissions that are granted to the Subject. 
e Validity period - The start time and the stop time for which the ACL entry is valid. 
¢ ACL entry tag - A user-defined string value associated with the ACL entry. 


The service provider can modify the caller-provided initial ACL entry to conform to any innate 
resource-access policy that the service provider may be required to enforce. If the initial ACL entry 
provided by the caller contains values or permissions that are not supported by the service provider, then 
the service provider can modify the initial ACL appropriately or can fail the request to create the new 
resource. Service providers list their supported AuthorizationTag values in their Module Directory 
Services primary record. 


NOTES 


The KeyData field of the CSSM_KEY structureis allocated by the CSP. The application is required to free this 
memory using the cSSM_FreeKey () (CSSM API), or CSP_FreeKey() (CSP SPI), function or with the memory 
functions registered for the cSPHandle. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CSP_KEY_LABEL ALREADY_EXISTS 
CSSMERR_CSP_PUBLIC_KEY_INCONSISTENT 
CSSMERR_CSP_PRIVATE_KEY_ALREADY_EXIST 
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SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 
CSSM_WrapKey 

Functions for the CSP SPI: 
CSP_WrapKey 
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UnwrapKeyP 


NAME 
UnwrapK eyP - Unwrap the wrapped keys with privilege (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_UnwrapKeyP 
(CSSM_CC_HANDLE CCHandle, 

const CSSM_KEY *PublicKey, 

const CSSM_WRAP_KEY *WrappedKey, 
uint32 KeyUsage, 

uint32 KeyA 
const CSSM 


oa 
ATA *KeyLabel, 

const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry, 
CSSM_KEY_PTR UnwrappedKey, 

CSSM_DATA_PTR DescriptiveData, 

CSSM_PRIVILEGE Privilege) 


Ud 


wm 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 
Privilege (input) 

The privilege to be applied during the cryptographic operation. 
See CSSM_UnwrapKey. 


DESCRIPTION 


This function is similar to CSSM_UnwrapKey (). It also accepts a USEE tag as a privilege request parameter. 
CSSM checks that either its own privilege set or the Application's privilege set (if the Application is signed) 
includes the tag. I f the tag is found and the service provider privilege set indicates that it is supported, the tag 
is forwarded to the service provider. 


NOTES 


The KeyData field of the CSSM_KEY structureis allocated by the CSP. The application is required to free this 
memory using the CSSM_FreeKey () function or with the memory functions registered for the CSPHandle. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 
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CSSMERR_CSP_KEY_LABEL ALREADY_EXISTS 
CSSMERR_CSP_PUBLIC_KEY_INCONSISTENT 
CSSMERR_CSP_PRIVATE_KEY_ALREADY_EXIST 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


478 


VerifyData 
NAME 
VerifyData: CSSM_VerifyData, CSP_VerifyData - Verify input buffer data (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 
CSSM_RETURN CSSMAPI CSSM_VerifyData 
(CSSM_CC_HANDLE CCHandle, 

const CSSM_DATA *DataBufs, 

uint32 DataBufCount, 
CSSM_ALGORITHMS DigestAlgorithm, 


const CSSM_DATA *Signature) 


CSSM_RETURN CSSMCSPI CSP_VerifyData 
(CSSM_CSP_HANDLE CSPHandle, 
CSSM_CC_HANDLE CCHandle, 

const CSSM_CONTEXT *Context, 

const CSSM_DATA *DataBufs, 

uint32 DataBufCount, 
CSSM_ALGORITHMS DigestAlgorithm, 
const CSSM_DATA *Signature) 


LIBRARY 


Common Security Services M anager library (cdsa$incssm300_shr.exe) 


API PARAMETERS 


CCHandle (input) 


The handle that describes the context of this cryptographic operation used to link to the 
CSP-managed information. 


Dat aBufs (input) 
A pointer toa vector of CSSM_DATA structures that contain the data to be operated on. 
Dat aBufCount (input) 


The number of DataBufs to be verified. 


DigestAlgorithm (input) 


If verifying just a digest, specifies the type of digest. |n this case, the context should only 
specify the encryption algorithm. If not verifying just a digest, it must be 
CSSM_ALGID_NONE. In this case, the context should specify the combination 
digest/encryption algorithm. 


Signature (input) 


A pointer toa CSSM_DATA structure which contains the signature and the size of the 
signature. 
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SPI PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform up calls to CSSM for the memory functions managed by CSSM. 


Context (input) 
Pointer to CSSM_ CONTEXT structure that describes the attributes with this context. 


DESCRIPTION 


This function verifies all data contained in the set of input buffers based on the input signature. 


Verifying can include digesting the data and decrypting the digest (from the signature) or verifying just the 
digest (already calculated by the application). | f digesting the data and decrypting the digest, then the context 
should specify both digest and decryption algorithms (for example, CSSM_ALGID_MD5WithRSA). In this 
case, the DigestAlgorithm parameter must be set to CSSM_ALGID_NONE. If signing just the digest, then 
the context should specify just the decryption algorithm and the DigestAlgorithm parameter should specify 
the type of digest (for example, CSSM_ALGID_MD5). Also, DataBufCount must be 1. 


If the signing algorithm is not reversible or strictly limits the size of the signed data, then the algorithm can 
specify verification without digesting. In this case, the verify operation is performed on theinput data and the 
size of the input data is restricted by the service provider. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CSP_INPUT_LENGTH_ERROR 
CSSMERR_CSP_VERIFY_FAILED 

CSSMERR_CSP_INVALID_SIGNATURE 
CSSMERR_CSP_INVALID_DIGEST_ALGORITHM 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 

CSSM_SignData, CSSM_VerifyDatalnit, CSSM_VerifyDataUpdate CSSM_VerifyDataF inal 
Functions for the CSP SPI: 

CSP_SignData, CSP_VerifyDatal nit, CSP_VerifyDataU pdate CSP_VerifyDataF inal 
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VerifyDataF inal 


NAME 


VerifyDataF inal: CSSM_VerifyDataFinal, CSP_VerifyDataFinal - Finalize the staged verify data 
(CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_VerifyDataFinal 
(CSSM_CC_HANDLE CCHandle, 

const CSSM_DATA *Signature) 

SPI: 

CSSM_BOOL CSSMCSPI CSP_VerifyDataFinal 
(CSSM_CSP_HANDLE CSPHandle, 
CSSM_CC_HANDLE CCHandle, 

const CSSM_DATA *Signature) 


LIBRARY 


Common Security Services M anager library (cdsa$incssm300_shr.exe) 


API PARAMETERS 


CCHandle (input) 


The handle that describes the context of this cryptographic operation used to link to the 
CSP-managed information. 


Signature (input) 


A pointer toa CSSM_DATA structure which contains the starting address for the signature 
to verify against and the length of the signature in bytes. 


SPI PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform up calls to CSSM for the memory functions managed by CSSM. 


DESCRIPTION 


This function finalizes the staged verify data function. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 
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CSSMERR_CSP_INPUT_LENGTH_ERROR 
CSSMERR_CSP_VERIFY_FAILED 
CSSMERR_CSP_INVALID_SIGNATURE 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 

CSSM_VerifyData, CSSM_VerifyDatal nit, CSSM_VerifyDataU pdate 
Functions for the CSP SPI: 

CSP_VerifyData, CSP_VerifyDatal nit, CSP_VerifyDataU pdate 
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VerifyDatal nit 


NAME 


VerifyDatal nit: CSSM_VerifyDatal nit, CSP_VerifyDatal nit - Initialize the staged verify data 
(CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_VerifyDataInit 
(CSSM_CC_HANDLE CCHandle) 

SPI: 
CSSM_RETURN CSSMCSPI CSP_VerifyDataInit 
(CSSM_CSP_HANDLE CSPHandle, 
CSSM_CC_HANDLE CCHandle, 

const CSSM_CONTEXT *Context) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


API PARAMETERS 


CCHandle (input) 


The handle that describes the context of this cryptographic operation used to link to the 
CSP-managed information. 


SPI PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform up calls to CSSM for the memory functions managed by CSSM. 


Context (input) 
Pointer to CSSM_ CONTEXT structure that describes the attributes with this context. 


DESCRIPTION 


This function initializes the staged verify data function. 


For staged operations, a combination operation selecting both a digesting algorithm and a verification 
algorithm must be specified. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 
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ERRORS 
Errors are described in the CDSA Technical Standard. 


None specific to this call. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 

CSSM_VerifyDataUpdate, CSSM _VerifyDataFinal, CSSM_VerifyData 
Functions for the CSP SPI: 

CSP_VerifyDataU pdate CSP_VerifyDataFinal, CSP_VerifyData 
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VerifyDataU pdate 


NAME 


VerifyDataU pdate: CSSM_VerifyDataU pdate, CSP_VerifyDataU pdate - Continue the staged 
verification (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_VerifyDataUpdate 
(CSSM_CC_HANDLE CCHandle, 

const CSSM_DATA *DataBufs, 

uint32 DataBufCount) 

SPI: 
CSSM_RETURN CSSMCSPI CSP_VerifyDataUpdate 
(CSSM_CSP_HANDLE CSPHandle, 

CSSM_CC_HANDLE CCHandle, 

const CSSM_DATA *DataBufs, 

uint32 DataBufCount) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


API PARAMETERS 


CCHandle (input) 


The handle that describes the context of this cryptographic operation used to link to the 
CSP-managed information. 


DataBufs (input) 
A pointer toa vector of CSSM_DATA structures that contain the data to be operated on. 
Dat aBufCount (input) 


The number of DataBufs to be verified. 


SPI PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform calls to CSSM for the memory functions managed by CSSM. 


DESCRIPTION 


This function continues the staged verification process over all data contained in the set of input. Verification 
will be based on the signature presented as input when finalizing the staged verification process. 
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RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


None specific to this call. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 

CSSM_VerifyData, CSSM_VerifyDatal nit, CSSM_VerifyDataF inal 
Functions for the CSP SPI: 

CSP_VerifyData, CSP_VerifyDatal nit, CSP_VerifyDataF inal 
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VerifyDevice 


NAME 


VerifyDevice: CSSM_VerifyDevice, CSP_VerifyDevice - Cause the cryptographic module to perform 
a self verification and integrity check (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_VerifyDevice 
(CSSM_CSP_HANDLE CSPHandle, 

const CSSM_DATA *DeviceCert) 

SPI: 
CSSM_RETURN CSSMCSPI CSP_VerifyDevice 
(CSSM_CSP_HANDLE CSPHandle, 

const CSSM_DATA *DeviceCert) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform this function. If a NULL handleis specified, CSSM returns error. 


DeviceCert (input) 


Pointer to CSSM_DATA structure that contains data that identifies the cryptographic 
device. 


DESCRIPTION 


This function triggers the cryptographic module to perform self verification and integrity checking. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CSP_DEVICE_VERIFY_FAILED 
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SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 
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VerifyMac 


NAME 
VerifyM ac: CSSM_VerifyMac, CSP_VerifyMac - Verify the message authentication code (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 
CSSM_RETURN CSSMAPI CSSM_VerifyMac 
(CSSM_CC_HANDLE CCHandle, 

const CSSM_DATA *DataBufs, 

uint32 DataBufCount, 


const CSSM_DATA *Mac) 


CSSM_RETURN CSSMCSPI CSP_VerifyMac 
(CSSM_CSP_HANDLE CSPHandle, 
CSSM_CC_HANDLE CCHandle, 

const CSSM_CONTEXT *Context, 

const CSSM_DATA *DataBufs, 

uint32 DataBufCount, 

const CSSM_DATA *Mac) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


API PARAMETERS 


CCHandle (input) 


The handle that describes the context of this cryptographic operation used to link to the 
CSP-managed information. 


Dat aBufs (input) 
A pointer toa vector of CSSM_DATA structures that contain the data to be operated on. 
Dat aBufCount (input) 


The number of DataBufs. 


Mac (input) 
A pointer tothe CSSM_DATA structure containing the MAC to verify. 


SPI PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform calls to CSSM for the memory functions managed by CSSM. 


Context (input) 
Pointer to CSSM_ CONTEXT structure that describes the attributes with this context. 
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DESCRIPTION 


This function verifies the message authentication code over all data contained in the set of input buffers 
based on the input signature. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CSP_INPUT_LENGTH_ERROR 
CSSMERR_CSP_VERIFY_FAILED 
CSSMERR_CSP_INVALID_SIGNATURE 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 

CSSM_VerifyMacl nit, CSSM_VerifyMacU pdate, CSSM_VerifyM acFinal 
Functions for the CSP SPI: 

CSP_VerifyM acl nit, CSP_VerifyMacU pdate, CSP_VerifyM acF inal 
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VerifyMacF inal 


NAME 


VerifyM acF inal: CSSM_VerifyMacFinal, CSP_VerifyMacFinal - Finalize the staged message 
authentication code (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_VerifyMacFinal 
(CSSM_CC_HANDLE CCHandle, 

const CSSM_DATA *Mac) 

SPI: 
CSSM_RETURN CSSMCSPI CSP_VerifyMacFinal 
(CSSM_CSP_HANDLE CSPHandle, 
CSSM_CC_HANDLE CCHandle, 

const CSSM_DATA *Mac) 


LIBRARY 


Common Security Services M anager library (cdsa$incssm300_shr.exe) 


API PARAMETERS 


CCHandle (input) 


The handle that describes the context of this cryptographic operation used to link to the 
CSP-managed information. 


Mac (input) 
A pointer tothe CSSM_DATA structure containing the MAC to verify. 


SPI PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform calls to CSSM for the memory functions managed by CSSM. 


DESCRIPTION 


This function finalizes the staged message authentication code verification function. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 
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CSSMERR_CSP_INPUT_LENGTH_ERROR 
CSSMERR_CSP_VERIFY_FAILED 
CSSMERR_CSP_INVALID_SIGNATURE 


COMMENTS FOR SPI 


The output is returned to the caller as specified in Buffer Management for Cryptographic Services. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 

CSSM_VerifyMac, CSSM_VerifyMaclnit, CSSM_VerifyMacU pdate 
Functions for the CSP SPI: 

CSP_VerifyMac, CSP_VerifyM acl nit, CSP_VerifyMacU pdate 
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VerifyMaciI nit 


NAME 


VerifyM acl nit: CSSM_VerifyMacdi nit, CSP_VerifyMaclI nit - Initialize the staged message 
authentication code (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_VerifyMacInit 
(CSSM_CC_HANDLE CCHandle) 

SPI: 
CSSM_RETURN CSSMCSPI CSP_VerifyMacInit 
(CSSM_CSP_HANDLE CSPHandle, 
CSSM_CC_HANDLE CCHandle, 

const CSSM_CONTEXT *Context) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


API PARAMETERS 


CCHandle (input) 


The handle that describes the context of this cryptographic operation used to link to the 
CSP-managed information. 


SPI PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform calls to CSSM for the memory functions managed by CSSM. 


Context (input) 
Pointer to CSSM_ CONTEXT structure that describes the attributes with this context. 


DESCRIPTION 


This function initializes the staged message authentication code verification function. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


None specific to this call. 
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SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 

CSSM_VerifyMac, CSSM_VerifyMacU pdate, CSSM_VerifyMacF inal 
Functions for the CSP SPI: 

CSP_VerifyMac, CSP_VerifyMacU pdate CSP_VerifyM acF inal 
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VerifyMacU pdate 
NAME 


VerifyM acU pdate: CSSM_VerifyMacUpdate, CSP_VerifyM acU pdate - Continue the staged process 


of verifying the message authentication code (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 

CSSM_RETURN CSSMAPI CSSM_VerifyMacUpdate 
(CSSM_CC_HANDLE CCHandle, 

const CSSM_DATA *DataBufs, 

uint32 DataBufCount) 

SPI: 
CSSM_RETURN CSSMCSPI CSP_VerifyMacUpdate 
(CSSM_CSP_HANDLE CSPHandle, 
CSSM_CC_HANDLE CCHandle, 

const CSSM_DATA *DataBufs, 

uint32 DataBufCount) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


API PARAMETERS 


CCHandle (input) 


The handle that describes the context of this cryptographic operation used to link to the 
CSP-managed information. 


DataBufs (input) 
A pointer toa vector of CSSM_DATA structures that contain the data to be operated on. 
Dat aBufCount (input) 


The number of DataBufs. 


SPI PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform calls to CSSM for the memory functions managed by CSSM. 


DESCRIPTION 


This function continues the staged process of verifying the message authentication code over all data in the 
set of input buffers. Verification will be based on the authentication code presented as input when finalizing 


the staged verification process. 


495 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


None specific to this call. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 

CSSM_VerifyMac, CSSM_VerifyMacl nit, CSSM_VerifyM acF inal 
Functions for the CSP SPI: 

CSP_VerifyMac, CSP_VerifyM acl nit, CSP_VerifyMacF inal 
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WrapKey 
NAME 


WrapK ey: CSSM_WrapKey, CSP_WrapKey - Wrap a key using the context (CDSA) 


SYNOPSIS 


#include <cssm.h> 


API: 
CSSM_RETURN CSS 
(CSSM_CC_HANDLE 


MAPI CSSM _WrapKey 
CCHandle, 


const CSSM_ACCE 
const CSSM_KEY 


SS_CREDENTIALS *AccessCred, 
*Key, 


const CSSM_DATA *DescriptiveData, 


CSSM_WRAP_KEY_P 
SPL s 
CSSM_RETURN CSS 
(CSSM_CSP_HAND 


TR WrappedKey) 


MCSPI CSP_WrapKey 


iF CSPHandle, 


CSSM_CC_HANDLE 


const CSSM_CONT 


const CSSM_ACCE 


CCHandle, 
EXT *Context, 
SS_CREDENTIALS *AccessCred, 


const CSSM_KEY 


*Key, 


const CSSM_DATA *DescriptiveData, 


CSSM_WRAP_KEY_P 
CSSM_PRIVILEGE 


LIBRARY 


TR WrappedKey, 
Privilege) 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


API PARAMETERS 


CCHandle (input) 


The handle to the context that describes this cryptographic operation. 


AccessCred (input) 


Key (input) 


A pointer to the set of one or more credentials required to access the private or secret key to 
be exported from the CSP. The credentials structure can contain an immediate value for the 
credential, such as a passphrase, or the caller can specify a callback function the CSP can 
use to obtain one or more credentials. 


A pointer to the key to be wrapped. 


DescriptiveData (input/optional) 


A pointer toa CSSM_DATA structure containing additional descriptive data to be 
associated and included with the key during the wrapping operation. The caller and the 
wrapping algorithm incorporate knowledge of the structure of the descriptive data. If the 
wrapping algorithm does not accept additional descriptive data, then this parameter must 
be NULL. If the wrapping algorithm accepts descriptive data, the corresponding 
unwrapping algorithm can be used to extract the descriptive data and the key. 


WrappedKey (output) 
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A pointer toa CSSM_WRAP_KEY structure that returns the wrapped key. 


SPI PARAMETERS 


CSPHandle (input) 


The handle that describes the add-in Cryptographic Service Provider module used to 
perform up-calls to CSSM for the memory functions managed by CSSM. 


Context (input) 
Pointer to CSSM_ CONTEXT structure that describes the attributes with this context. 
Privilege (input) 


The export privilege to be applied during the cryptographic operation. This parameter is 
forwarded to the CSP after CSSM verifies the caller and service provider privilege set 
includes the specified PRIVILEGE. 


DESCRIPTION 


This function wraps the supplied key using the context. It allows a key to be exported from a CSP. Four types 
of wrapping exist: 


1. Wrap a symmetric key with a symmetric key. 

2. Wrap a symmetric key with an asymmetric public key. 

3. Wrap an asymmetric private key with a symmetric key. 

4. Wrap an asymmetric private key with an asymmetric public key. 


For types 1 and 3, a symmetric context should be provided. For types 2 and 4, an asymmetric context is 
provided. If thereisa CSSM_ATTRIBUTE_WRAPPED_KEY_FORMAT argument in the context represented 
by the CCHandle, the value of the attribute specifies the format of the wrapped key. If this argument is not 
present, the symmetric key is wrapped according to CMS for types 1 and 3, and according to PK CS8 for types 
2 and 4. If the wrapping algorithm in the context is CSSM_ALGID_ NONE, then the key is returned in raw 
format, if permitted and supported by the CSP (in this case the 
CSSM_ATTRIBUTE_WRAPPED_KEY_FORMAT attribute is ignored). All significant key attributes are 
incorporated into the KeyHeader of the returned WrappedKey, such that the state of the key can be fully 
restored by the unwrap process. 


The CSP can require that the cryptographic context includes access credentials for authentication and 
authorization checks when using the secret or private key. 


NOTES 


The KeyData field of the CSSM_KEY structureis allocated by the CSP. The application is required to free this 
memory using the CSSM_FreeKey () (CSSM API), or CSP_FreeKey () (CSP SPI) function, or with the memory 
functions registered for the cSPHandle. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 
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ERRORS 


Errors are described in the CDSA Technical Standard. 


None specific to this call. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 

Functions for the CSSM API: 
CSSM_UnwrapKey 
Functions for the CSP SPI: 
CSP_UnwrapKey 
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WrapKeyP 
NAME 
WrapkK eyP - Wrap a key with privilege (CDSA) 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI CSSM_WrapKeyP 
(CSSM_CC_HANDLE CCHandle, 

const CSSM_ACCESS_ CREDENTIALS *AccessCred, 
const CSSM_KEY *Key, 

const CSSM_DATA *DescriptiveData, 
CSSM_WRAP_KEY_PTR WrappedKey, 
CSSM_PRIVILEGE Privilege) 


LIBRARY 


Common Security Services Manager library (cdsa$incssm300_shr.exe) 


PARAMETERS 
Privilege (input) 

The privilege to be applied during the cryptographic operation. 
See CSSM_WrapKey. 


DESCRIPTION 


This function is similar to CSSM_WrapKey (). It also accepts a USEE tag as a privilege request parameter. 
CSSM checks that either its own privilege set or the application's privilege set (if the application is signed) 
includes the tag. If the tag is found, and the service provider privilege set indicates that it is supported, the 
tag is forwarded to the service provider. 


NOTES 


The KeyData field of the CSSM_KEY structureis allocated by the CSP. The application is required to free this 
memory using the cSSM_FreeKey() functon, or with the memory functions registered for the cSPHandle. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 
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SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 
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Elective Module Manager APIs 


These functions are implemented by an Elective Module M anager and are made available to CSSM in a func- 
tion table. 


For a module attach of a service provider managed by an EMM, CSSM invokes 
ModuleM anagerAuthenticate(). Upon successful completion of this function, the elective module manager 
returns its function table to CSSM with the following modules: 


Deregister DispatchTable 
EventN otifyM anager 
Initialize 

ModuleM anagerAuthenticate 
RefreshF unctionT able 
Register DispatchTable 


Terminate 
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DeregisterDispatchTable 
NAME 
DeregisterDispatchTable - Invalidate CSSM pointers toEMM 
SYNOPSIS 
#include <cssm.h> 


(void) 


PARAMETERS 


None. 


DESCRIPTION 


This EMM -defined function is invoked by CSSM once for each CSSM_ModuleDetach() operation issued 
against a service provider of the type managed by the EMM. CSSM uses this function to inform the EMM 
that the set of CSSM function pointers provided to the EMM when the session was attached are no longer 
valid. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 
Functions: Registe-DispatchTable 
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EventNotifyManager 
NAME 


EventN otifyM anager - Receive an event notification 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI EventNotifyManager 
(const CSSM_MANAGER_EVENT_NOTIFICATION *EventDescription) 


PARAMETERS 


EventDescription 


A structure containing the following fields: 


Dest inationModuleManagerType (input) 


The unique service mask identifying the destination module manager. 


SourceModuleManagerType (input) 
The unique service mask identifying the source module manager. 
Event (input) 


An identifier indicating the event that has or will take place. 


Event Id (input/optional) 


A unique identifier associated with this event notification. It must be used in any reply 
notification that results from this event notification. 


EventData (input/optional) 


Arbitrary data (required or informational) for this event. 


DESCRIPTION 


This function receives an event notification from another module manager. The source manager is identified 
by its service mask. The specified event type is interpreted by the received and the appropriate actions must 
be taken in response. EventId and EventData are optional. The Event Idis specified by the source module 
manager when a reply is expected. The destination module manager must use this identifier when replying to 
the event notification. The EventData is additional data or descriptive information provided to the 
destination manager. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


CSSMERR_CSSM_MODULE_MANAGER_NOT_FOUND 
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SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 
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Initialize 
NAME 


Initialize - Verify module version 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI Initialize 
(uint32 VerMajor, 
uint32 VerMinor) 


PARAMETERS 


VerMa jor (input) 


The major version number of the CSSM that is invoking this module manager. 


VerMinor (input) 


The minor version number of the CSSM that is invoking this module manager. 


DESCRIPTION 


This function checks whether the current version of the module is compatible with the CSSM version 
specified as input and performs any module-manager-specific setup activities. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 


indicates success. All other values represent an error condition. 


ERRORS 


Errors are described in the CDSA Technical Standard. 


CSSMERR_CSSM_MODULE_MANAGER_INITIALIZI 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 


Functions: Terminate 


E_ FAIL 
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ModuleManagerAuthenticate 
NAME 
ModuleM anagerAuthenticate - Module manager authentication 


SYNOPSIS 


#include <cdsa/mds.h> 


CSSM_RETURN CSSMAPI ModuleManagerAuthenticat 
(CSSM_KEY_HIERARCHY KeyHierarchy, 

const CSSM_GUID *CssmGuid, 

const CSSM_GUID *AppGuid, 
CSSM_MANAGER_REGISTRATION_INFO_PTR FunctionTable) 


PARAMETERS 
KeyHierarchy (input) 


The CSSM_KEY_HIERARCHY flag indicating which embedded key(s) CSSM should use 
when verifying the integrity of the module manager. 


CssmGuid (input) 


A CSSM_GUID value identifying the calling CSSM. The elective module manager can use 
this value to locate the signed manifest credentials for CSSM. 


AppGuid (input/optional) 


A CSSM_GUID value identifying the application who invoked the calling CSSM. The 
elective module manager can use this value to locate the signed manifest credentials for the 
application. 


FunctionTable (output) 


A set of function pointers for EMM -defined functions used by CSSM to communicate state 
changes related to module attach and module detach operations. 


DESCRIPTION 


This function should perform the elective module manager's half of the bilateral authentication procedure 
with CSSM. The CssmGuid is used to locate the CSSM's credentials to be verified. The credentials area 
zipped, signed manifest. 


The KeyHierarchy indicates which public key should be used as the root when checking the integrity of the 
module manager. The AppGuid is used to locate the application's signed manifest credentials. The elective 
module manager must check the application's credentials to verify the application's authorization. If no 
privileges are requested, then the application is not required to provide a GUID nor a set of signed manifest 
credentials. 


Upon successful completion, the elective module manager returns its function table to the calling CSSM. The 
EMM function table contains the set of EMM entry points that CSSM uses to notify the module manager of 
significant events such as module attach and module detach requests issued by an application, and event 
notifications issued by other module managers. 


This function symbol must be exported by the elective module manager, so CSSM can invoke this function 
upon completion of the loading process. 
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This function is the first module manager interface invoked by CSSM after loading and invoking the main 
entry point. In particular, the elective module manager's initialize function is invoked by CSSM after this 
function has successfully completed execution. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 
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RefreshF unctionTable 


NAME 
RefreshF unctionTable - Gets EMM-defined API function 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI RefreshFunctionTable 
(CSSM_FUNC_NAME_ADDR_PTR FuncNameAddrPtr, 
uint32 NumOfFuncNameAddr) 


PARAMETERS 


FuncNameAddrPtr (input/output) 
A pointer to a table mapping function names to EMM-defined APIs. 
NumOfFuncNameAddr (input) 


The number of entries in the table referenced by FuncNameAddrPtr. 


DESCRIPTION 


CSSM invokes this function to obtain the EMM-defined API function. The table is returned to CSSM in 
FuncNameAddrPtr and CSSM returns the table to the application. The application uses this table to invoke 
the security services defined by the EMM's service category. CSSM must obtain and forward the API table to 
the application on behalf of the EMM because the application is not aware of the optional nature of the EMM. 
Applications use CSSM to obtain the API function table for basic module managers and elective module 
managers, providing a uniform application programming model. 


If the Elective Module Manager needs the service provider's SPI function table in order to initialize the API 
function table, the EMM can obtain the SPI function table by invoking the CSSM -provided service 
cssm_GetAttachFunctions(). Theservice module may implement only a subset of the defined functions and 
the EMM may wish to manage these functions in a particular manner through the API mapping. The elective 
module manager uses the SPI function table to dispatch application calls for service to attached modules. 


Multiple applications and multiple instances of a service module can be concurrently active. The single 
elective module manager is responsible for managing all of these concurrent sessions. After completing 
initialization of the API function table, the EMM returns the refreshed API table to CSSM. 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_ OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 
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SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 
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RegisterDispatchTable 
NAME 
Register DispatchTable - Provide the EMM with CSSM function pointers 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI RegisterDispatchTable 
(CSSM_STATE_FUNCS_PTR CssmStateCallTable) 


PARAMETERS 


CssmStateCallTable (input) 


A table of function pointers for the set of CSSM -defined functions the elective module 
manager can use to query and control the state of an attach-session between an application 
and a service provider managed by the module manager. 


DESCRIPTION 


This EMM -defined function is invoked by CSSM once for each CSSM_ModuleAttach (), operation requesting a 
service provider of the type managed by the EMM. CSSM uses this function to provide the EMM with a set of 
CSSM function pointers. The EMM invokes these functions at anytime during the life cycle of the 
attach-session to obtain information about the current state and to modify the current state of the attach 
session. 


When the attach-session is terminated, CSSM informs the module manager by invoking the EMM function 
DeregisterDispatchTable(). The corresponding set of CSSM state functions become invalid at that time 


RETURN VALUE 


A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 
indicates success. All other values represent an error condition. 


ERRORS 
Errors are described in the CDSA Technical Standard. 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 
Functions: DeregisterDispatchTable 
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Terminate 


NAME 


Terminate - Clean up module-manager-specific activities 


SYNOPSIS 


#include <cssm.h> 


CSSM_RETURN CSSMAPI Terminate 


(void) 


PARAMETERS 


None. 


DESCRIPTION 


This function performs any module-manager-specific cleanup activities in preparation for unloading of the 
elective module manager. 


RETURN VALUE 
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK 


indicates success. All other values represent an error condition. 


ERRORS 


Errors are described in the CDSA Technical Standard. 


CSSMERR_CSSM_1] 


EMM_AUTHI 


SEE ALSO 


Books 


Inta CDSA Application Devdoper's Guide 


Online Help 


Functions: Initialize 


ENTICATI 


E FAIL! 


ED. 
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Open Source Notice 


A Open Source Notice 


IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING. By downloading, 
copying, installing or using the software you agree to this license. If you do not agree to this license, do not 
download, install, copy or use the software. 


Intel Open Source License for CDSA/CSSM Implementation 
(BSD License with Export Notice) 


Copyright (c) 1996-2000 Intel Corporation 
All rights reserved. 


Redistribution and use in source and binary forms, with or without modification, are permitted provided that 
the following conditions are met: 


e Redistributions of source code must retain the above copyright notice, this list of conditions and the 
following disclaimer. 


e Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the 
following disclaimer in the documentation and/or other materials provided with the distribution. 


¢ Neither the name of the Intel Corporation nor the names of its contributors may be used to endorse or 
promote products derived from this software without specific prior written permission. 


THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 
DISCLAIMED. IN NO EVENT SHALL INTEL OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 
LIABILITY, WHETHERIN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF 
THE POSSIBILITY OF SUCH DAMAGE. 


EXPORT LAWS: THIS LICENSE ADDS NO RESTRICTIONS TO THE THE EXPORT LAWS OF YOUR 

J URISDICTION. It is licensee's responsibility to comply with any export regulations applicable in licensee's 
jurisdiction. Under CURRENT (J uly 2000) U.S. export regulations this software is eligible for export from the 
U.S. and can be downloaded by or otherwise exported or reexported worldwide EXCEPT to U.S. embargoed 
destinations which include Cuba, Iraq, Libya, North Korea, Iran, Syria, Sudan, Afghanistan and any other 
country to which the U.S. has embargoed goods and services. 


Copyright (c) 1996-2000 I ntel Corporation. All rights reserved. 
* Other brands and names are the property of their respective owners. 
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Glossary 


AAL See Application Adaptation Layer (AAL). 


AC Authorization Computation service provider 
module. Synonymous with Authorization 
Computation Module (ACM). 


Accountability A mechanism whereby the action of 
a user or a machine can be traced to that user or 
machine. A user's action may be audited and stored 
in a data bank called an audit trail. Subsequent 
searching of the audit trail can match events to the 
event instigator. |n the commercial world, 
accountability is important to establish accurate 
billing procedures. 


Application Adaptation Layer (AAL) An 
interface between CDSA and applications designed 
to use CDSA services. 


Asymmetric Algorithms Cryptographic 
algorithms using one key to encrypt and a second 
key to decrypt. They are often called public-key 
algorithms. One key is called the public key, and the 
other is called the private key or secret key. 


Attach A process whereby an application obtains a 
service provider module handle, viaan ATTACH call 
to CSSM. A service provider module can bea 
dynamic load module added at runtime on demand 
or a statically resident module. 


Authentication A user or machine's identity must 
be established before establishing a connection toa 
computer. Authentication is the process of proving 
identity to the satisfaction of the 
permission-granting authority. 


Authorization Permission for an entity to perform 
an action upon an object. Authorization is evaluated 
by a set of access control rules. Evaluation typically 
includes authentication of the requesting entity. The 
result of the evaluation should be conveyed to an 
agent that can enable the requested action upon the 
target object. 


Biometric input The gathering of data froma 
personal, unique source, such as fingerprints, retina 
patterns, or human voice, for the purposes of 
verification or authorization. 


BSAFE A cryptographic toolkit from RSA Data 
Security Incorporated. 


Glossary 


CDSA See Common Data Security Architecture 
(CDSA). 


Certificate A combination of an asymmetric public 
key and other identifying private information, which 
is digitally signed by a private key soit can be 
verified. Seealso Digital certificate 


Certificate chain The hierarchical chain of all 
other certificates used to sign the current certificate. 
This includes the Certificate Authority (CA) who 
signs the certificate, the CA who signed that CA's 
certificate, and so on. There is no limit to the depth 
of the certificate chain. 


Certificate signing The Certificate Authority (CA) 
can sign certificates it issues or cosign certificates 
issued by another CA. In a general signing model, an 
object signs an arbitrary set of one or more objects. 
Hence, any number of signers can attest to an 
arbitrary set of objects. The arbitrary objects could 
be, for example, pieces of a document for libraries of 
executable code. 


Certificate validity date A start date and a stop 
date for the validity of a certificate. If a certificate 
expires, the Certificate Authority (CA) may issue a 
new certificate. 


Certification Authority An entity that guarantees 
or sponsors a certificate. For example, a credit card 
company signs a cardholder's certificate to ensure 
that the cardholder is who he or she claims to be. 
The credit card company is a certificate authority. 
Certificate authorities issue, verify, and revoke 
certificates. 


CL Certificate Library service provider module. 
Synonymous with Certificate Library Module 
(CLM). 


Common Data Security Architecture (CDSA) A 
set of layered security services that address 
communications and data security problems in the 
emerging Internet and Intranet application space. 
CDSA consists of three basic layers: 


e A set of system security services 


« TheCommon Security Services Manager 
(CSSM) 


e Add-in security modules (CSPs, TPs, CLs, DLs, 
ACs) 
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Glossary 
Common Security Services Manager (CSSM) 


Common Security Services Manager (CSSM) 


The central layer of the Common Data Security 
Architecture (CDSA) that defines the following 
service components: 


¢ Cryptographic Services M anager 

e Trust Policy Services Manager 

¢ Certificate Library Services Manager 

e« Data Storage Library Services M anager 
e Authorization Computation M anager 

e Elective Module Manager 

e Integrity Services Manager 


e Security Context Manager 


CSSM binds together all the security services 
required by applications. In particular, it facilitates 
linking digital certificates to cryptographic actions 
and trust protocols. 


Confidentiality | nformation is revealed only to 
those who are authorized to see it. Confidentiality 
can be provided through an authorization and access 
control mechanism. It can also be provided through 
encryption and decryption operations, which limit 
data access to those who possess the cryptographic 
keys required to decrypt the information. 


Cryptographic algorithm A method or defined 
mathematical process for implementing a 
cryptography operation. A Cryptographic algorithm 
may specify the procedure for encrypting and 
decrypting a byte stream, digitally signing an object, 
computing the hash of an object, or generating a 
random number. 


Cryptographic Service Providers (CSPs) 
Modules that provide secure key storage and 
cryptographic functions. The modules may be 
software only or hardware with software drivers. 
The cryptographic functions provided may include: 
¢ Bulk encryption and decryption 

¢ Digital signing 


¢ Cryptographic hash 
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¢ Random number generation 


« Key exchange 


Cryptography The art and science of using 
mathematics to secure information and create a high 
degree of trust in the electronic media. 


Cryptoki The name of the PK CS#11 Version 1.0 
standard published by RSA Laboratories. The 
standard specifies the interface for accessing 
cryptographic services performed by a removable 
device. For additional information, refer to 
http://www.rsasecurity.com. 


CSP SeeCryptographic Service Providers (CSPs). 


CSSM SeeCommon Security Services Manager 
(CSSM). 


Digital certificate The binding of some 
identification to a public key in a particular domain, 
as attested to directly or indirectly by the digital 
signature of the owner of that domain. A digital 
certificate is an unforgeable credential in 
cyberspace. The certificate is issued by a trusted 
authority and covered by that party's digital 
signature. The certificate may attest to the 
certificate holder's identity or may authorize certain 
actions by the certificate holder. A certificate may 
include multiple signatures and may attest to 
multiple objects or multiple actions. 


Digital signature A data block that was created by 
applying a cryptographic signing algorithm to some 
other data using a secret key. Digital signatures may 
be used to: 


e Authenticate the source of a message, data, or 
document. 


e Verify that the content of a message has not been 
modified since it was signed by the sender. 


e¢ Verify that a public key belongs to a particular 
person. 


Typical digital signing algorithms include RSA 
signaturing and DSS, the Digital Signature 
Standard defined by NIST FIPS Pub 186. 

DL Database Library service provider module. 


EISL Embedded Integrity Services Library. 


Glossary 


EMM Elective module manager. 


ESW Electronicshrink-wrap. A term used to refer to 
an aggregate collection of data files identified by a 
manifest or bill of materials. 


Generic Cryptographic Services (GCS) A set of 
services and associated APIs designed to provide 
key-based cryptographic operations to applications. 
GCS predates CDSA. GCS requirements were based 
on early hardware-based cryptographic devices 
where cryptographic keys were retained within the 
device. Some | nternet applications require the 
secured transmission of cryptographic keys. The 
CDSA Cryptographic Service APIs accommodate 
both types of requirements. 


Generic Security Services (GSS) A set of services 
and associated APIs defined by the International 
Engineering Task Force (IETF). The defined APIs 
support concurrent applications in authenticating 
each other, delegating rights and privileges to each 
other, and using confidentiality and integrity 
verification services to secure communications 
between the applications. 


GUID Globally unique identifier. 


Hash algorithm A cryptographic algorithm used to 
compress a variable-size input stream into a unique, 
fixed-size output value. The function is one-way, 
meaning the input value cannot be derived from the 
output value. A cryptographically strong hash 
algorithm is collision-free, meaning unique input 
values produce unique output values. Hashing is 
typically used in digital signing algorithms. Example 
hash algorithms include MD and MD2 from RSA 
Data Security. MD5, also from RSA Data Security, 
hashes a variable-size input stream into a 128-bit 
output value. SHA, a Secure Hash Algorithm 
published by the U.S. Government, produces a 
160-bit hash value from a variable-size input 
stream. 


HRS Human Recognition Services. HRS is aCSSM 
Elective Module Manager intended to providea 
high-level generic authentication model suited for 
any form of human authentication. Particular 
emphasis has been made in the design on its 
suitability for authentication using biometric 
technology. 


Glossary 


Glossary 
Module Directory Services (MDS) 


Integrity | nformation is said to have integrity if 
that data has not been modified or altered since the 
point in time when an authorized agent intended the 
data to be static. Information integrity is important 
for all data types including authorization data and 
authentication credentials. 


Key Management Public-private key pairs are 
items that need to be securely managed. A key may 
be lost, stolen, or compromised. | f this happens, the 
key (and in fact, the key pair) must be nulled. 
Whatever task the key was used for, a new key must 
be issued and used. In the case of the lost key, a 
duplicate should be available. If not, the data 
protected by the lost key may itself be lost. The null 
public key must be advertised as invalid. It will be 
listed in a data bank called a revocation list. The 
new public key must be distributed to those entitled 
to have it. 


Leaf certificate The certificatein a certificate 
chain that has not been used to sign another 
certificate in that chain. The leaf certificate is signed 
directly or transitively by all other certificates in the 
chain. 


Manifest A digital signature of a file, created using 
certificates. The digital signature takes the form of 
a separate file called a manifest. The manifest 
contains the encrypted digest of the target file and 
the X509 certificates of the signers. This data is 
sufficient to guarantee the identity of the signer of a 
file and the authenticity of the file's contents. 


MDS See Module Directory Services (MDS). 


Message Digest The digital fingerprint of an input 
stream. A cryptographic hash function is applied to 
an input message of arbitrary length and returns a 

fixed-size output, which is called the digest value. 


Meta-information Descriptive information 
specified by a service provider module and stored in 
MDS. This information advertises the module's 
services. CSSM supports application queries for this 
information. The information may change at 
runtime. 


Module Directory Services (MDS) A 
platform-independent registration service for 
managing executable code modules and their 
associated signed integrity credentials. 
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Glossary 
Nonce 


Nonce A nonrepeating value, usually but not 
necessarily random. 


OID Object identifier. 


Owned certificate A certificate whose associated 
private key resides in a local CSP. Digital signature 
algorithms require the private key when signing 
data. A system may supply certificates it owns along 
with signed data to allow others to verify the 
signature. A system uses certificates that it does not 
own to verify signatures created by others. 


PKI See Public Key Infrastructure (PKI). 


Private key The cryptographic key used to 
decipher or sign messages in public-key 
cryptography. This key is kept secret by its owner. 


Public key The cryptographic key used to encrypt 
messages in public-key cryptography. The public key 
is available to multiple users (for example, the 
public). 


Public Key Infrastructure (PKI) The agreed 
infrastructure, ultimately to be applied worldwide, 
in which secure electronic business (eCommerce, 
banking, legal transactions) and secure electronic 
welfare (medical welfare, state and government 
provision for pensions, social security, and so forth) 
can function securely using the private-public key 
method of cryptography. 


PVC Pointer validation checking. 


Random number generator A function that 
generates cryptographically strong random numbers 
that cannot be easily guessed by an attacker. 
Random numbers are often used to generate session 
keys. 


Root certificate The prime certificate, such as the 
official certificate of a corporation or government 
entity. The root certificate is positioned at the top of 
the certificate hierarchy in its domain, and it 
guarantees the other certificates in its certificate 
chain. The root certificate's public key is the 
foundation of signature verification in its domain. 


RSA RSA Data Security, Incorporated, Bedford, MA. 
Producers of the BSAFE toolkit. 
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Secret key A cryptographic key used with 
symmetric algorithms, usually to provide 
confidentiality. 


Secure Electronic Transaction (SET) A 
specification designed to utilize technology for 
authenticating the parties involved in payment card 
purchases on any type of online network, including 
the Internet. SET focuses on maintaining 
confidentiality of information, ensuring message 
integrity, and authenticating the parties involved in 
a transaction. More information about SET is 
available at: http://www.setco.org/. Seealso Secure 
Sockets Layer (SSL). 


Secure Sockets Layer (SSL) Also known as Above 
Transport Layer Security (TLS). A security protocol 
that prevents eavesdropping, tampering, or message 
forgery over the Internet. An SSL service negotiates 
a secure session between two communicating 
endpoints. Basic facilities include certificate-based 
authentication, end-to-end data integrity, and 
optional data privacy. SSL has been submitted to the 
IETF as an Internet Draft for Transport Layer 
Security (TLS). 


Security context A control structure that retains 
state information shared between a cryptographic 
service provider and the application agent 
requesting service from the CSP. A security context 
specifies CSP and application-specific values, such 
as required key length and desired hash functions. 


Security infrastructure An agreed infrastructure 
for the security of all electronic data transfer. Such 
an infrastructure would, in theory, lessen the need 
for organizations to construct trust domains. An 
international security infrastructure would facilitate 
the creation of a secure Internet. Presently, global 
efforts are more focussed on an architecture for 
Public K ey Infrastructure, seen by many as the 
blueprint for the infrastructure that will facilitate 
eCommerce. 


Security perimeter A conceptual perimeter or 
boundary of a computer system or local area 
network inside which the security is at a known 
level of competence. If data is required to cross this 
perimeter, it is prudent to pass all such data through 
a firewall. 
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Security-relevant event An event wherea 
CSP-provided function is performed, a security 
service provider module is loaded, or a breach of 
system security is detected. 


Security risk assessment An exercise performed 
by specialists to assess how vulnerable an enterprise 
is to various forms of security attack. The ideal 
outcome from this exercise is a recommended range 
of security measures, hardware, software, and 
procedural, which give a level of protection 
commensurate with the value of the assets that need 
to be protected. 


Session key A cryptographic key used to encrypt 
and decrypt data. The key is shared by two or more 
communicating parties, who use the key to ensure 
privacy of the exchanged data. 


SET See Secure Electronic Transaction (SET). 
Signature See Digital Signature 


Signature chain The hierarchical chain of signers, 
from the root certificate to the leaf certificate, ina 
certificate chain. 


Signing and sealing The electronic equivalent to 
the handwritten signature and the secure strong 
room. Precise ways of performing these actions may 
vary, but signing by digital signature and sealing 
(for transport or storage) by encryption is evolving 
towards internationally agreed protocols which will 
be acceptable to the commercial world, the legal 
profession, and governments. 


Single sign-on A mechanism whereby a single 
action of user authentication and authorization can 
permit a user to access all computers and systems 
where he has access permission, without the need to 
enter multiple passwords. Single sign-on reduces 
human error, a major component of systems failure. 


SmartC ard A card of the same dimensions as the 
magnetic-stripe credit card, but containing 
processing ability and memory storage space. 
Because the card can contain storage credentials 
and cryptographic keys and perform 
encryption/decryption operations, its power as a 
tamper-proof personal token for authentication 
makes it very attractive to a whole range of 
computer applications. 


SPI Service provider interface. 
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SPKI Simple public key infrastructure. Information 
about SPKI can be found at 
http://www.ietf.org/html.charters/spki-charter.html. 


SSL SeeSecure Sockets Layer (SSL). 


SSLeay A free implementation of the Secure 
Sockets Layer. Seealso Secure Sockets Layer 
(SSL). 


Symmetric algorithms Cryptographic algorithms 
that use a single secret key for encryption and 
decryption. Both the sender and receiver must know 
the secret key. Well known symmetric functions 
include DES (Data Encryption Standard) and IDEA. 
DES was endorsed by the U.S. Government as a 
standard in 1977. It's an encryption block cipher 
that operates on 64-bit blocks with a 56-bit key. It is 
designed to be implemented in hardware, and works 
well for bulk encryption. IDEA (International Data 
Encryption Algorithm) uses a 128-bit key. 


Token The logical view of a cryptographic device, as 
defined by a CSP's interface. A token can be 
hardware, a physical object, or software. A token 
contains information about its owner in digital form 
and about the services it provides for 
electronic-commerce and other communication 
applications. A token is a secure device. It may 
provide a limited or a broad range of cryptographic 
functions. Examples of hardware tokens are 
SmartCards and PMCIA cards. 


TP Trust Policy service provider module. 
Synonymous with Trust Policy Module (TPM). 


Trust domains A designated virtual area that has 
a known and accepted level of security, and thus a 
known and accepted level of trust. A local area 
network is an example of a domain that is likely to 
be trusted. Domains may be geographically wide 
ranging, and may be made up of subdomains. A 
domain is only as trustworthy as its weakest 
component. 


Verification A process performed to check the 
integrity of a message, to determine the sender of a 
message, or both. Different algorithms are used to 
support different modes of verification. 


A typical procedure supporting integrity verification 
is the combination of a one-way hash function anda 
reversible digital signaturing algorithm. A one-way 
hash of the message is computed. The hash value is 
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signed by encrypting it with a private key. The 
message and the encrypted hash value are sent toa 
receiver. The recipient recomputes the one-way 
hash, decrypts the signed hash value, and compares 
it with the computed hash. If the values match, then 
the message has not been tampered since it was 
signed. 


The identity of a sender can be verified by a 
challenge-response protocol. The recipient sends the 
message sender a random challenge value. The 
original sender uses its private key to sign the 
challenge value and returns the result to the 
receiver. The receiver uses the corresponding public 
key to verify the signature over the challenge value. 
If the signature is valid, the sender is the holder of 
the private key. If the receiver can reliably associate 
the corresponding public key with the named/known 
entity, then the identity of the sender is said to have 
been verified. 


Web of trust A trust network among people who 
know and communicate with each other. Digital 
certificates are used to represent entities in the web 
of trust. Any pair of entities can determine the 
extent of trust between the two, based on their 
relationship in the web. 


X509v3 X.509 Version 3. This standard defines the 
contents and structure of a digital certificate The 
specification is |TU-T Recommendation X.509, Data 
Networks and Open System Communications 
Directory: Authentication Framework, 06/97. This 
certificate format constitutes a widely accepted basis 
for a public key infrastructure. To support the PKI, 
certificates of this form are digitally signed and 
issued by certification authorities (CAs). 
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